{
    "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",