{
    "openapi": "3.0.0",
    "info": {
        "title": "POS & Inventory SaaS API",
        "description": "REST API for the multi-tenant POS and Inventory management platform. Every endpoint operates within the tenant of the authenticated user - there is no way to address another tenant's data through this API, the same isolation the web application enforces. Authenticate via POST /api/v1/auth/login to receive a bearer token, then send it as `Authorization: Bearer {token}` on every subsequent request.",
        "contact": {
            "name": "API Support",
            "email": "support@pos-saas.test"
        },
        "version": "1.0.0"
    },
    "servers": [
        {
            "url": "/api/v1",
            "description": "Default API server"
        }
    ],
    "paths": {
        "/auth/login": {
            "post": {
                "tags": [
                    "Authentication"
                ],
                "summary": "Log in and receive an API token",
                "description": "Exchanges a tenant domain, email, and password for a bearer token. The tenant domain is required because email uniqueness in this system is scoped per tenant, not global - two different tenants may have a user with the same email address.",
                "operationId": "985cd5203e2d0a820e113f2f4fdb2847",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "tenant",
                                    "email",
                                    "password"
                                ],
                                "properties": {
                                    "tenant": {
                                        "description": "The tenant's registered domain",
                                        "type": "string",
                                        "example": "acme.pos-saas.test"
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "example": "owner@acme.test"
                                    },
                                    "password": {
                                        "type": "string",
                                        "format": "password",
                                        "example": "password"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Authenticated successfully",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "token": {
                                            "type": "string",
                                            "example": "1|abcdef1234567890"
                                        },
                                        "token_type": {
                                            "type": "string",
                                            "example": "Bearer"
                                        },
                                        "user": {
                                            "$ref": "#/components/schemas/User"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The tenant is suspended or its trial has expired"
                    },
                    "422": {
                        "description": "Invalid tenant, email, or password"
                    }
                }
            }
        },
        "/auth/logout": {
            "post": {
                "tags": [
                    "Authentication"
                ],
                "summary": "Revoke the current API token",
                "operationId": "a05022a34eef599e04fb0a5254375b84",
                "responses": {
                    "200": {
                        "description": "Logged out successfully"
                    },
                    "401": {
                        "description": "Not authenticated"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/auth/me": {
            "get": {
                "tags": [
                    "Authentication"
                ],
                "summary": "Get the currently authenticated user",
                "operationId": "e339e0e74860c0647fd1d41bbbbc13b2",
                "responses": {
                    "200": {
                        "description": "The current user",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "user": {
                                            "$ref": "#/components/schemas/User"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Not authenticated"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/dashboard": {
            "get": {
                "tags": [
                    "Dashboard"
                ],
                "summary": "Today's operational summary",
                "description": "The same data behind the tenant-facing dashboard's landing page: today's sales/purchases/profit, current inventory valuation, low-stock items, the last 30 days' top sellers, a 7-day sales trend, and the 10 most recent transactions.",
                "operationId": "07d2d0f81b9051bfc2a937097221e0ce",
                "responses": {
                    "200": {
                        "description": "The dashboard summary",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/DashboardSummary"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Not authenticated"
                    },
                    "403": {
                        "description": "Not authorized to view reports"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/inventory/stock": {
            "get": {
                "tags": [
                    "Inventory"
                ],
                "summary": "Current stock levels at a warehouse",
                "description": "Defaults to the first active warehouse if warehouse_id is omitted.",
                "operationId": "c827410198d896df94cfa48c06278474",
                "parameters": [
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "description": "Matches against product name or SKU",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "low_stock_only",
                        "in": "query",
                        "schema": {
                            "type": "boolean"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated stock levels",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/WarehouseStock"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Not authenticated"
                    },
                    "403": {
                        "description": "Not authorized to view stock"
                    },
                    "422": {
                        "description": "No warehouse exists yet"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/inventory/movements": {
            "get": {
                "tags": [
                    "Inventory"
                ],
                "summary": "Stock movement ledger (stock audit history)",
                "operationId": "47f9617b1555dda03258a023150a0371",
                "parameters": [
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "product_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated stock movement history",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/StockMovement"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Not authenticated"
                    },
                    "403": {
                        "description": "Not authorized to view stock movements"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/products": {
            "get": {
                "tags": [
                    "Products"
                ],
                "summary": "List products",
                "description": "Paginated, filterable list of the current tenant's catalog products.",
                "operationId": "c821c7f9e41e08594ad4eae5a99e812e",
                "parameters": [
                    {
                        "name": "search",
                        "in": "query",
                        "description": "Matches against name, SKU, or barcode",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "category_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "brand_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "active",
                                "inactive"
                            ]
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated list of products",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Product"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Not authenticated"
                    },
                    "403": {
                        "description": "Not authorized to view products"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Products"
                ],
                "summary": "Create a product",
                "operationId": "a59d7d76c37cb085c473698dba983938",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "name",
                                    "sku",
                                    "category_id",
                                    "unit_id",
                                    "purchase_price",
                                    "selling_price",
                                    "cost",
                                    "minimum_stock",
                                    "status"
                                ],
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "example": "Instant Coffee 200g"
                                    },
                                    "slug": {
                                        "type": "string",
                                        "example": "instant-coffee-200g",
                                        "nullable": true
                                    },
                                    "sku": {
                                        "type": "string",
                                        "example": "SKU-00123"
                                    },
                                    "barcode": {
                                        "type": "string",
                                        "example": "8991234567890",
                                        "nullable": true
                                    },
                                    "category_id": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "brand_id": {
                                        "type": "integer",
                                        "example": 1,
                                        "nullable": true
                                    },
                                    "unit_id": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "description": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "purchase_price": {
                                        "type": "number",
                                        "format": "float",
                                        "example": 15000
                                    },
                                    "selling_price": {
                                        "type": "number",
                                        "format": "float",
                                        "example": 20000
                                    },
                                    "cost": {
                                        "type": "number",
                                        "format": "float",
                                        "example": 15000
                                    },
                                    "minimum_stock": {
                                        "type": "integer",
                                        "example": 10
                                    },
                                    "status": {
                                        "type": "string",
                                        "example": "active",
                                        "enum": [
                                            "active",
                                            "inactive"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Product created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Product"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Not authenticated"
                    },
                    "403": {
                        "description": "Not authorized to create products"
                    },
                    "422": {
                        "description": "Validation failed"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/products/{product}": {
            "get": {
                "tags": [
                    "Products"
                ],
                "summary": "Get a single product",
                "operationId": "8cacdd61a07ddbbac50707e7a6b41036",
                "parameters": [
                    {
                        "name": "product",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The product",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Product"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Not authenticated"
                    },
                    "404": {
                        "description": "Product not found"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Products"
                ],
                "summary": "Update a product",
                "operationId": "5246c892eeb357f0062990ef2445f859",
                "parameters": [
                    {
                        "name": "product",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "name",
                                    "sku",
                                    "category_id",
                                    "unit_id",
                                    "purchase_price",
                                    "selling_price",
                                    "cost",
                                    "minimum_stock",
                                    "status"
                                ],
                                "properties": {
                                    "name": {
                                        "type": "string"
                                    },
                                    "slug": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "sku": {
                                        "type": "string"
                                    },
                                    "barcode": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "category_id": {
                                        "type": "integer"
                                    },
                                    "brand_id": {
                                        "type": "integer",
                                        "nullable": true
                                    },
                                    "unit_id": {
                                        "type": "integer"
                                    },
                                    "description": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "purchase_price": {
                                        "type": "number",
                                        "format": "float"
                                    },
                                    "selling_price": {
                                        "type": "number",
                                        "format": "float"
                                    },
                                    "cost": {
                                        "type": "number",
                                        "format": "float"
                                    },
                                    "minimum_stock": {
                                        "type": "integer"
                                    },
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "active",
                                            "inactive"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Product updated",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Product"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Not authenticated"
                    },
                    "403": {
                        "description": "Not authorized to update this product"
                    },
                    "404": {
                        "description": "Product not found"
                    },
                    "422": {
                        "description": "Validation failed"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Products"
                ],
                "summary": "Delete a product",
                "description": "Fails with 409 if the product is still referenced by stock movements, sales, or purchases.",
                "operationId": "6e75da057de15ec8736d072573cefc6f",
                "parameters": [
                    {
                        "name": "product",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "204": {
                        "description": "Product deleted"
                    },
                    "401": {
                        "description": "Not authenticated"
                    },
                    "403": {
                        "description": "Not authorized to delete this product"
                    },
                    "404": {
                        "description": "Product not found"
                    },
                    "409": {
                        "description": "Product is still referenced elsewhere and cannot be deleted"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/purchase-invoices": {
            "get": {
                "tags": [
                    "Purchase Invoices"
                ],
                "summary": "List supplier invoices",
                "operationId": "8ddf89b3d5fc4aaaa84f67b6c9c3d7c6",
                "parameters": [
                    {
                        "name": "search",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "supplier_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "unpaid",
                                "partially_paid",
                                "paid"
                            ]
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated list of supplier invoices",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/PurchaseInvoice"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Not authenticated"
                    },
                    "403": {
                        "description": "Not authorized to view supplier invoices"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/purchase-invoices/{purchaseInvoice}": {
            "get": {
                "tags": [
                    "Purchase Invoices"
                ],
                "summary": "Get a single supplier invoice",
                "operationId": "6f710f5100aa1517ab50e9f17bd65994",
                "parameters": [
                    {
                        "name": "purchaseInvoice",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The supplier invoice",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/PurchaseInvoice"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Not authenticated"
                    },
                    "403": {
                        "description": "Not authorized to view supplier invoices"
                    },
                    "404": {
                        "description": "Invoice not found"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/purchase-orders": {
            "get": {
                "tags": [
                    "Purchase Orders"
                ],
                "summary": "List purchase orders",
                "operationId": "d0af9ee2243bdc81323a6295f4e01ee8",
                "parameters": [
                    {
                        "name": "search",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "supplier_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "draft",
                                "submitted",
                                "partially_received",
                                "received",
                                "cancelled"
                            ]
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated list of purchase orders",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/PurchaseOrder"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Not authenticated"
                    },
                    "403": {
                        "description": "Not authorized to view purchase orders"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Purchase Orders"
                ],
                "summary": "Create a purchase order",
                "description": "Always created as Draft, regardless of any status passed - matching the web app's behavior. Submit it separately through the web app to move it into the receiving workflow.",
                "operationId": "6dc44c32b3476c7c23358234f0bd0a78",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "supplier_id",
                                    "warehouse_id",
                                    "order_date",
                                    "items"
                                ],
                                "properties": {
                                    "supplier_id": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "warehouse_id": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "order_date": {
                                        "type": "string",
                                        "format": "date",
                                        "example": "2026-08-19"
                                    },
                                    "expected_date": {
                                        "type": "string",
                                        "format": "date",
                                        "example": "2026-08-26",
                                        "nullable": true
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "items": {
                                        "type": "array",
                                        "items": {
                                            "required": [
                                                "product_id",
                                                "quantity_ordered",
                                                "unit_cost"
                                            ],
                                            "properties": {
                                                "product_id": {
                                                    "type": "integer",
                                                    "example": 1
                                                },
                                                "tax_id": {
                                                    "type": "integer",
                                                    "example": 1,
                                                    "nullable": true
                                                },
                                                "quantity_ordered": {
                                                    "type": "integer",
                                                    "example": 100
                                                },
                                                "unit_cost": {
                                                    "type": "number",
                                                    "format": "float",
                                                    "example": 15000
                                                }
                                            },
                                            "type": "object"
                                        }
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Purchase order created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/PurchaseOrder"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Not authenticated"
                    },
                    "403": {
                        "description": "Not authorized to create purchase orders"
                    },
                    "422": {
                        "description": "Validation failed"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/purchase-orders/{purchaseOrder}": {
            "get": {
                "tags": [
                    "Purchase Orders"
                ],
                "summary": "Get a single purchase order, including its line items",
                "operationId": "9caee51167ad5ead16fcb2c1ee4322f3",
                "parameters": [
                    {
                        "name": "purchaseOrder",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The purchase order",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/PurchaseOrder"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Not authenticated"
                    },
                    "403": {
                        "description": "Not authorized to view purchase orders"
                    },
                    "404": {
                        "description": "Purchase order not found"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/sales": {
            "get": {
                "tags": [
                    "Sales"
                ],
                "summary": "List sales",
                "description": "A user without the blanket sales.view permission only sees sales they personally processed as cashier.",
                "operationId": "a2e981e47fac573d9961105517d022df",
                "parameters": [
                    {
                        "name": "search",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "unpaid",
                                "partially_paid",
                                "paid"
                            ]
                        }
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "cashier_id",
                        "in": "query",
                        "description": "Ignored unless the caller holds sales.view",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated list of sales",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Sale"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Not authenticated"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Sales"
                ],
                "summary": "Check out a sale (POS transaction)",
                "description": "Creates a sale, its line items, and its payments atomically. Prices and costs are pulled live from each product - only product_id and quantity are accepted per line. A sale left with an outstanding balance requires customer_id (a credit sale needs a member to bill).",
                "operationId": "678fe5b736161e60f22fb2cc5ae9e827",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "warehouse_id",
                                    "items",
                                    "payments"
                                ],
                                "properties": {
                                    "warehouse_id": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "customer_id": {
                                        "type": "integer",
                                        "example": 1,
                                        "nullable": true
                                    },
                                    "discount_code": {
                                        "type": "string",
                                        "example": "WELCOME10",
                                        "nullable": true
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "items": {
                                        "type": "array",
                                        "items": {
                                            "required": [
                                                "product_id",
                                                "quantity"
                                            ],
                                            "properties": {
                                                "product_id": {
                                                    "type": "integer",
                                                    "example": 1
                                                },
                                                "quantity": {
                                                    "type": "integer",
                                                    "example": 2
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "payments": {
                                        "type": "array",
                                        "items": {
                                            "required": [
                                                "method"
                                            ],
                                            "properties": {
                                                "method": {
                                                    "type": "string",
                                                    "example": "cash",
                                                    "enum": [
                                                        "cash",
                                                        "transfer",
                                                        "qris"
                                                    ]
                                                },
                                                "amount": {
                                                    "type": "number",
                                                    "format": "float",
                                                    "example": 44400,
                                                    "nullable": true
                                                },
                                                "tendered_amount": {
                                                    "description": "Cash only",
                                                    "type": "number",
                                                    "format": "float",
                                                    "example": 50000,
                                                    "nullable": true
                                                },
                                                "reference": {
                                                    "type": "string",
                                                    "nullable": true
                                                }
                                            },
                                            "type": "object"
                                        }
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Sale completed",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Sale"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Not authenticated"
                    },
                    "403": {
                        "description": "Not authorized to create sales"
                    },
                    "409": {
                        "description": "The sale conflicts with the current state (e.g. a credit sale with no customer)"
                    },
                    "422": {
                        "description": "Validation failed, an invalid discount code, or insufficient stock"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/sales/{sale}": {
            "get": {
                "tags": [
                    "Sales"
                ],
                "summary": "Get a single sale, including its items and payments",
                "operationId": "605b541499c35e890668ec0de4e59e6b",
                "parameters": [
                    {
                        "name": "sale",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The sale",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Sale"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Not authenticated"
                    },
                    "403": {
                        "description": "Not authorized to view this sale"
                    },
                    "404": {
                        "description": "Sale not found"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        }
    },
    "components": {
        "schemas": {
            "DashboardSummary": {
                "properties": {
                    "today_sales": {
                        "properties": {
                            "total_revenue": {
                                "description": "Wraps the plain array App\\Domain\\Reporting\\Services\\DashboardService::\nsummary() returns - not a single Eloquent model, so this reads from\n$this->resource by array key throughout rather than relying on\nJsonResource's magic property proxying, and flattens the embedded\nProduct models in top_products into a minimal shape rather than\nserializing them raw.",
                                "type": "number",
                                "format": "float",
                                "example": 1250000
                            },
                            "transaction_count": {
                                "type": "integer",
                                "example": 18
                            },
                            "payment_breakdown": {
                                "type": "object",
                                "example": {
                                    "cash": 800000,
                                    "qris": 450000
                                },
                                "additionalProperties": {
                                    "type": "number",
                                    "format": "float"
                                }
                            }
                        },
                        "type": "object"
                    },
                    "today_purchase": {
                        "properties": {
                            "total_spend": {
                                "type": "number",
                                "format": "float",
                                "example": 500000
                            },
                            "order_count": {
                                "type": "integer",
                                "example": 2
                            }
                        },
                        "type": "object"
                    },
                    "today_profit": {
                        "properties": {
                            "gross_profit": {
                                "type": "number",
                                "format": "float",
                                "example": 300000
                            },
                            "gross_margin_percent": {
                                "type": "number",
                                "format": "float",
                                "example": 24
                            }
                        },
                        "type": "object"
                    },
                    "inventory_value": {
                        "properties": {
                            "total_valuation": {
                                "type": "number",
                                "format": "float",
                                "example": 45000000
                            },
                            "low_stock_count": {
                                "type": "integer",
                                "example": 3
                            }
                        },
                        "type": "object"
                    },
                    "low_stock_items": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "product_name": {
                                    "type": "string",
                                    "example": "Instant Coffee 200g"
                                },
                                "warehouse_name": {
                                    "type": "string",
                                    "example": "Main Warehouse"
                                },
                                "quantity": {
                                    "type": "integer",
                                    "example": 4
                                },
                                "minimum_stock": {
                                    "type": "integer",
                                    "example": 10
                                }
                            },
                            "type": "object"
                        }
                    },
                    "top_products": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "product_id": {
                                    "type": "integer",
                                    "example": 1
                                },
                                "product_name": {
                                    "type": "string",
                                    "example": "Instant Coffee 200g"
                                },
                                "quantity_sold": {
                                    "type": "integer",
                                    "example": 42
                                },
                                "revenue": {
                                    "type": "number",
                                    "format": "float",
                                    "example": 840000
                                }
                            },
                            "type": "object"
                        }
                    },
                    "sales_trend": {
                        "type": "object",
                        "example": {
                            "2026-08-13": 950000,
                            "2026-08-14": 1120000
                        },
                        "additionalProperties": {
                            "type": "number",
                            "format": "float"
                        }
                    },
                    "recent_transactions": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "type": {
                                    "type": "string",
                                    "example": "Sale"
                                },
                                "reference": {
                                    "type": "string",
                                    "example": "INV-000123"
                                },
                                "party": {
                                    "type": "string",
                                    "example": "Walk-in Customer"
                                },
                                "amount": {
                                    "type": "number",
                                    "format": "float",
                                    "example": 44400
                                },
                                "status": {
                                    "type": "string",
                                    "example": "Paid"
                                },
                                "date": {
                                    "type": "string",
                                    "format": "date-time"
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "Product": {
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 1
                    },
                    "name": {
                        "type": "string",
                        "example": "Instant Coffee 200g"
                    },
                    "slug": {
                        "type": "string",
                        "example": "instant-coffee-200g"
                    },
                    "sku": {
                        "type": "string",
                        "example": "SKU-00123"
                    },
                    "barcode": {
                        "type": "string",
                        "example": "8991234567890",
                        "nullable": true
                    },
                    "description": {
                        "type": "string",
                        "nullable": true
                    },
                    "category": {
                        "type": "string",
                        "example": "Beverages",
                        "nullable": true
                    },
                    "brand": {
                        "type": "string",
                        "example": "Kapal Api",
                        "nullable": true
                    },
                    "unit": {
                        "type": "string",
                        "example": "Pack",
                        "nullable": true
                    },
                    "purchase_price": {
                        "type": "number",
                        "format": "float",
                        "example": 15000
                    },
                    "selling_price": {
                        "type": "number",
                        "format": "float",
                        "example": 20000
                    },
                    "cost": {
                        "type": "number",
                        "format": "float",
                        "example": 15000
                    },
                    "margin": {
                        "type": "number",
                        "format": "float",
                        "example": 5000
                    },
                    "margin_percentage": {
                        "type": "number",
                        "format": "float",
                        "example": 25
                    },
                    "minimum_stock": {
                        "type": "integer",
                        "example": 10
                    },
                    "status": {
                        "type": "string",
                        "example": "active",
                        "enum": [
                            "active",
                            "inactive"
                        ]
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                },
                "type": "object"
            },
            "PurchaseInvoice": {
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 1
                    },
                    "invoice_number": {
                        "type": "string",
                        "example": "SUP-INV-000045"
                    },
                    "status": {
                        "type": "string",
                        "example": "unpaid",
                        "enum": [
                            "unpaid",
                            "partially_paid",
                            "paid"
                        ]
                    },
                    "supplier": {
                        "type": "string",
                        "example": "Global Foods"
                    },
                    "purchase_order": {
                        "type": "string",
                        "example": "PO-000123",
                        "nullable": true
                    },
                    "invoice_date": {
                        "type": "string",
                        "format": "date"
                    },
                    "due_date": {
                        "type": "string",
                        "format": "date",
                        "nullable": true
                    },
                    "total_amount": {
                        "type": "number",
                        "format": "float",
                        "example": 1665000
                    },
                    "paid_amount": {
                        "type": "number",
                        "format": "float",
                        "example": 0
                    },
                    "outstanding_balance": {
                        "type": "number",
                        "format": "float",
                        "example": 1665000
                    },
                    "notes": {
                        "type": "string",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "PurchaseOrderItem": {
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 1
                    },
                    "product": {
                        "type": "string",
                        "example": "Instant Coffee 200g"
                    },
                    "quantity_ordered": {
                        "type": "integer",
                        "example": 100
                    },
                    "quantity_received": {
                        "type": "integer",
                        "example": 40
                    },
                    "quantity_returned": {
                        "type": "integer",
                        "example": 0
                    },
                    "unit_cost": {
                        "type": "number",
                        "format": "float",
                        "example": 15000
                    },
                    "line_total": {
                        "type": "number",
                        "format": "float",
                        "example": 1500000
                    }
                },
                "type": "object"
            },
            "PurchaseOrder": {
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 1
                    },
                    "po_number": {
                        "type": "string",
                        "example": "PO-000123"
                    },
                    "status": {
                        "type": "string",
                        "example": "draft",
                        "enum": [
                            "draft",
                            "submitted",
                            "partially_received",
                            "received",
                            "cancelled"
                        ]
                    },
                    "supplier": {
                        "type": "string",
                        "example": "Global Foods"
                    },
                    "warehouse": {
                        "type": "string",
                        "example": "Main Warehouse"
                    },
                    "order_date": {
                        "type": "string",
                        "format": "date"
                    },
                    "expected_date": {
                        "type": "string",
                        "format": "date",
                        "nullable": true
                    },
                    "subtotal": {
                        "type": "number",
                        "format": "float",
                        "example": 1500000
                    },
                    "tax_amount": {
                        "type": "number",
                        "format": "float",
                        "example": 165000
                    },
                    "total_amount": {
                        "type": "number",
                        "format": "float",
                        "example": 1665000
                    },
                    "notes": {
                        "type": "string",
                        "nullable": true
                    },
                    "items": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/PurchaseOrderItem"
                        }
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                },
                "type": "object"
            },
            "SaleItem": {
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 1
                    },
                    "product_name": {
                        "description": "Snapshotted at sale time, unaffected by later product edits",
                        "type": "string",
                        "example": "Instant Coffee 200g"
                    },
                    "product_sku": {
                        "type": "string",
                        "example": "SKU-00123"
                    },
                    "unit_price": {
                        "type": "number",
                        "format": "float",
                        "example": 20000
                    },
                    "quantity": {
                        "type": "integer",
                        "example": 2
                    },
                    "quantity_returned": {
                        "type": "integer",
                        "example": 0
                    },
                    "line_total": {
                        "type": "number",
                        "format": "float",
                        "example": 40000
                    }
                },
                "type": "object"
            },
            "SalePayment": {
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 1
                    },
                    "method": {
                        "type": "string",
                        "example": "cash",
                        "enum": [
                            "cash",
                            "transfer",
                            "qris"
                        ]
                    },
                    "amount": {
                        "type": "number",
                        "format": "float",
                        "example": 40000
                    },
                    "tendered_amount": {
                        "type": "number",
                        "format": "float",
                        "example": 50000,
                        "nullable": true
                    },
                    "change_amount": {
                        "type": "number",
                        "format": "float",
                        "example": 10000,
                        "nullable": true
                    },
                    "reference": {
                        "type": "string",
                        "nullable": true
                    },
                    "paid_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                },
                "type": "object"
            },
            "Sale": {
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 1
                    },
                    "sale_number": {
                        "type": "string",
                        "example": "INV-000123"
                    },
                    "status": {
                        "type": "string",
                        "example": "paid",
                        "enum": [
                            "unpaid",
                            "partially_paid",
                            "paid"
                        ]
                    },
                    "customer": {
                        "type": "string",
                        "example": "Siti Rahayu",
                        "nullable": true
                    },
                    "cashier": {
                        "$ref": "#/components/schemas/User"
                    },
                    "subtotal": {
                        "type": "number",
                        "format": "float",
                        "example": 40000
                    },
                    "discount_amount": {
                        "type": "number",
                        "format": "float",
                        "example": 0
                    },
                    "tax_amount": {
                        "type": "number",
                        "format": "float",
                        "example": 4400
                    },
                    "total_amount": {
                        "type": "number",
                        "format": "float",
                        "example": 44400
                    },
                    "paid_amount": {
                        "type": "number",
                        "format": "float",
                        "example": 44400
                    },
                    "outstanding_balance": {
                        "type": "number",
                        "format": "float",
                        "example": 0
                    },
                    "due_date": {
                        "type": "string",
                        "format": "date",
                        "nullable": true
                    },
                    "notes": {
                        "type": "string",
                        "nullable": true
                    },
                    "items": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/SaleItem"
                        }
                    },
                    "payments": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/SalePayment"
                        }
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                },
                "type": "object"
            },
            "StockMovement": {
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 1
                    },
                    "product": {
                        "type": "string",
                        "example": "Instant Coffee 200g"
                    },
                    "warehouse": {
                        "type": "string",
                        "example": "Main Warehouse"
                    },
                    "type": {
                        "type": "string",
                        "example": "sale_out",
                        "enum": [
                            "initial",
                            "adjustment_in",
                            "adjustment_out",
                            "transfer_in",
                            "transfer_out",
                            "purchase_in",
                            "purchase_return_out",
                            "sale_out",
                            "sale_return_in",
                            "opname_adjustment_in",
                            "opname_adjustment_out"
                        ]
                    },
                    "quantity": {
                        "type": "integer",
                        "example": 2
                    },
                    "quantity_before": {
                        "type": "integer",
                        "example": 76
                    },
                    "quantity_after": {
                        "type": "integer",
                        "example": 74
                    },
                    "note": {
                        "type": "string",
                        "nullable": true
                    },
                    "created_by": {
                        "type": "string",
                        "example": "Ada Owner",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                },
                "type": "object"
            },
            "User": {
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 1
                    },
                    "name": {
                        "type": "string",
                        "example": "Ada Owner"
                    },
                    "email": {
                        "type": "string",
                        "format": "email",
                        "example": "owner@acme.test"
                    },
                    "phone": {
                        "type": "string",
                        "example": "081234567890",
                        "nullable": true
                    },
                    "roles": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "example": [
                            "Owner"
                        ]
                    }
                },
                "type": "object"
            },
            "WarehouseStock": {
                "properties": {
                    "product": {
                        "type": "string",
                        "example": "Instant Coffee 200g"
                    },
                    "sku": {
                        "type": "string",
                        "example": "SKU-00123"
                    },
                    "warehouse": {
                        "type": "string",
                        "example": "Main Warehouse"
                    },
                    "quantity": {
                        "type": "integer",
                        "example": 74
                    },
                    "minimum_stock": {
                        "type": "integer",
                        "example": 10
                    },
                    "is_low_stock": {
                        "type": "boolean",
                        "example": false
                    }
                },
                "type": "object"
            }
        },
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "bearerFormat": "Sanctum personal access token",
                "scheme": "bearer"
            }
        }
    },
    "tags": [
        {
            "name": "Authentication",
            "description": "Login, logout, and current-user endpoints"
        },
        {
            "name": "Products",
            "description": "Catalog product management"
        },
        {
            "name": "Purchase Orders",
            "description": "Purchase orders placed with suppliers"
        },
        {
            "name": "Purchase Invoices",
            "description": "Suppliers' bills against purchase orders, and their payment status"
        },
        {
            "name": "Sales",
            "description": "Point-of-sale transactions"
        },
        {
            "name": "Inventory",
            "description": "Current stock levels and the stock movement ledger"
        },
        {
            "name": "Dashboard",
            "description": "Today's operational summary"
        }
    ]
}