{ "openapi": "3.0.0", "info": { "title": "Data Collection and Payment Management API", "description": "Production-ready API for managing users, suppliers, products, collections, rates, and payments with multi-unit tracking, versioned rates, and automated payment calculations. Built on Clean Architecture, SOLID, DRY, and KISS principles.\n *\n * **Authentication:**\n * All protected endpoints require JWT Bearer token authentication. Include the token in the Authorization header.\n *\n * **Rate Limiting:**\n * - Public endpoints (login, register): 5 requests per minute\n * - Standard protected endpoints: 60 requests per minute\n * - Report endpoints: 30 requests per minute (resource intensive)\n *\n * **Version Control:**\n * Update operations on suppliers, products, rates, collections, and payments include version conflict checking to prevent concurrent modification issues. Returns 409 on conflict.\n *\n * **Audit Logging:**\n * All authenticated requests are logged for audit purposes including user actions, IP addresses, and timestamps.", "contact": { "name": "API Support", "email": "support@ledger.com" }, "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" }, "version": "1.0.0" }, "servers": [ { "url": "http://localhost:8000/api", "description": "Local Development Server" }, { "url": "https://api.ledger.com/api", "description": "Production Server" } ], "paths": { "/register": { "post": { "tags": [ "Authentication" ], "summary": "Register a new user", "description": "Create a new user account with email and password", "operationId": "register", "requestBody": { "description": "User registration data", "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "password", "password_confirmation" ], "properties": { "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "john@example.com" }, "password": { "type": "string", "format": "password", "minLength": 8, "example": "password123" }, "password_confirmation": { "type": "string", "format": "password", "example": "password123" }, "role_id": { "description": "Role ID (optional)", "type": "integer", "example": 2, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "User registered successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "User registered successfully" }, "data": { "properties": { "user": { "type": "object" }, "token": { "type": "string" }, "token_type": { "type": "string", "example": "bearer" }, "expires_in": { "type": "integer", "example": 3600 } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "object" } }, "type": "object" } } } } } } }, "/login": { "post": { "tags": [ "Authentication" ], "summary": "Login user", "description": "Authenticate user and return JWT token", "operationId": "login", "requestBody": { "description": "User login credentials", "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "admin@ledger.com" }, "password": { "type": "string", "format": "password", "example": "password" } }, "type": "object" } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Login successful" }, "data": { "properties": { "user": { "type": "object" }, "token": { "type": "string" }, "token_type": { "type": "string", "example": "bearer" }, "expires_in": { "type": "integer", "example": 3600 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid credentials" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "object" } }, "type": "object" } } } } } } }, "/me": { "get": { "tags": [ "Authentication" ], "summary": "Get authenticated user", "description": "Get the currently authenticated user's information", "operationId": "me", "responses": { "200": { "description": "User data retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/logout": { "post": { "tags": [ "Authentication" ], "summary": "Logout user", "description": "Revoke the user's JWT token and invalidate the session", "operationId": "logout", "responses": { "200": { "description": "Logout successful", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Logout successful" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "500": { "description": "Server error during logout", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred during logout" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/refresh": { "post": { "tags": [ "Authentication" ], "summary": "Refresh JWT token", "description": "Get a new JWT token using the current token", "operationId": "refresh", "responses": { "200": { "description": "Token refreshed successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "token": { "type": "string" }, "token_type": { "type": "string", "example": "bearer" }, "expires_in": { "type": "integer", "example": 3600 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/collections": { "get": { "tags": [ "Collections" ], "summary": "Get all collections", "description": "Retrieve collections with multi-unit tracking and filtering options", "operationId": "getCollections", "parameters": [ { "name": "supplier_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "product_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "sort_by", "in": "query", "description": "Field to sort by", "required": false, "schema": { "type": "string", "default": "collection_date", "enum": [ "collection_date", "quantity", "total_amount", "created_at", "updated_at" ] } }, { "name": "sort_order", "in": "query", "description": "Sort order", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "Paginated collection list with supplier, product, user, and rate details", "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Collections" ], "summary": "Create new collection", "description": "Record a new collection with automatic rate lookup and amount calculation", "operationId": "createCollection", "requestBody": { "description": "Collection data with multi-unit quantity", "required": true, "content": { "application/json": { "schema": { "required": [ "supplier_id", "product_id", "collection_date", "quantity", "unit" ], "properties": { "supplier_id": { "description": "ID of the supplier", "type": "integer", "example": 1 }, "product_id": { "description": "ID of the product", "type": "integer", "example": 1 }, "collection_date": { "description": "Date of collection", "type": "string", "format": "date", "example": "2025-12-29" }, "quantity": { "description": "Quantity collected", "type": "number", "format": "float", "example": 50.5 }, "unit": { "description": "Unit of measurement", "type": "string", "example": "kg" }, "notes": { "description": "Additional notes", "type": "string", "example": "Quality grade A", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Collection created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Collection created successfully" }, "data": { "description": "Collection details with calculated amount", "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error or rate not found" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/collections/{id}": { "get": { "tags": [ "Collections" ], "summary": "Get collection by ID", "description": "Retrieve a specific collection with related supplier, product, user, and rate information", "operationId": "getCollectionById", "parameters": [ { "name": "id", "in": "path", "description": "Collection ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "Collection details", "type": "object" } }, "type": "object" } } } }, "404": { "description": "Collection not found" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Collections" ], "summary": "Update collection", "description": "Update collection details with automatic recalculation of rate and amount if necessary", "operationId": "updateCollection", "parameters": [ { "name": "id", "in": "path", "description": "Collection ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "description": "Updated collection data", "required": true, "content": { "application/json": { "schema": { "properties": { "supplier_id": { "type": "integer", "example": 1 }, "product_id": { "type": "integer", "example": 1 }, "collection_date": { "type": "string", "format": "date", "example": "2025-12-29" }, "quantity": { "type": "number", "format": "float", "example": 55 }, "unit": { "type": "string", "example": "kg" }, "notes": { "type": "string", "example": "Updated notes", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Collection updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Collection updated successfully" }, "data": { "description": "Updated collection with recalculated amount", "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "404": { "description": "Collection not found" }, "401": { "description": "Unauthenticated" }, "409": { "description": "Version conflict - resource was modified by another user", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Version conflict detected" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Collections" ], "summary": "Delete collection", "description": "Remove a collection record from the system", "operationId": "deleteCollection", "parameters": [ { "name": "id", "in": "path", "description": "Collection ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Collection deleted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Collection deleted successfully" } }, "type": "object" } } } }, "404": { "description": "Collection not found" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/payments": { "get": { "tags": [ "Payments" ], "summary": "Get all payments", "description": "Retrieve payments with filtering for advance, partial, and full payments", "operationId": "getPayments", "parameters": [ { "name": "supplier_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "advance", "partial", "full" ] } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "sort_by", "in": "query", "description": "Field to sort by", "required": false, "schema": { "type": "string", "default": "payment_date", "enum": [ "payment_date", "amount", "type", "created_at", "updated_at" ] } }, { "name": "sort_order", "in": "query", "description": "Sort order", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "Paginated payment list with supplier and user details", "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Payments" ], "summary": "Create new payment", "description": "Record a new payment (advance, partial, full, or adjustment) for a supplier", "operationId": "createPayment", "requestBody": { "description": "Payment data", "required": true, "content": { "application/json": { "schema": { "required": [ "supplier_id", "payment_date", "amount", "type" ], "properties": { "supplier_id": { "description": "ID of the supplier", "type": "integer", "example": 1 }, "payment_date": { "description": "Date of payment", "type": "string", "format": "date", "example": "2025-12-29" }, "amount": { "description": "Payment amount", "type": "number", "format": "float", "example": 5000 }, "type": { "description": "Type of payment", "type": "string", "enum": [ "advance", "partial", "full", "adjustment" ], "example": "partial" }, "reference_number": { "description": "Payment reference number", "type": "string", "example": "PAY-2025-001", "nullable": true }, "payment_method": { "description": "Payment method used", "type": "string", "example": "bank_transfer", "nullable": true }, "notes": { "description": "Additional notes", "type": "string", "example": "Payment for December collection", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Payment created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Payment created successfully" }, "data": { "description": "Payment details", "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/payments/{id}": { "get": { "tags": [ "Payments" ], "summary": "Get payment by ID", "description": "Retrieve a specific payment with related supplier and user information", "operationId": "getPaymentById", "parameters": [ { "name": "id", "in": "path", "description": "Payment ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "Payment details", "type": "object" } }, "type": "object" } } } }, "404": { "description": "Payment not found" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Payments" ], "summary": "Update payment", "description": "Update payment details with version control for concurrency", "operationId": "updatePayment", "parameters": [ { "name": "id", "in": "path", "description": "Payment ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "description": "Updated payment data", "required": true, "content": { "application/json": { "schema": { "properties": { "supplier_id": { "type": "integer", "example": 1 }, "payment_date": { "type": "string", "format": "date", "example": "2025-12-29" }, "amount": { "type": "number", "format": "float", "example": 5500 }, "type": { "type": "string", "enum": [ "advance", "partial", "full", "adjustment" ], "example": "partial" }, "reference_number": { "type": "string", "example": "PAY-2025-001-REV", "nullable": true }, "payment_method": { "type": "string", "example": "cash", "nullable": true }, "notes": { "type": "string", "example": "Updated payment notes", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Payment updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Payment updated successfully" }, "data": { "description": "Updated payment details", "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "404": { "description": "Payment not found" }, "401": { "description": "Unauthenticated" }, "409": { "description": "Version conflict - resource was modified by another user", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Version conflict detected" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Payments" ], "summary": "Delete payment", "description": "Remove a payment record from the system", "operationId": "deletePayment", "parameters": [ { "name": "id", "in": "path", "description": "Payment ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payment deleted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Payment deleted successfully" } }, "type": "object" } } } }, "404": { "description": "Payment not found" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/products": { "get": { "tags": [ "Products" ], "summary": "Get all products", "description": "Retrieve a paginated list of products with multi-unit support", "operationId": "getProducts", "parameters": [ { "name": "is_active", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "sort_by", "in": "query", "description": "Field to sort by", "required": false, "schema": { "type": "string", "default": "created_at", "enum": [ "name", "code", "base_unit", "created_at", "updated_at" ] } }, { "name": "sort_order", "in": "query", "description": "Sort order", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "Paginated product list", "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Products" ], "summary": "Create new product", "description": "Create a new product with multi-unit support", "operationId": "createProduct", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "code", "base_unit" ], "properties": { "name": { "type": "string", "example": "Tea Leaves" }, "code": { "type": "string", "example": "PROD001" }, "base_unit": { "type": "string", "example": "kg" }, "supported_units": { "type": "array", "items": { "type": "string" }, "example": [ "kg", "g", "lbs" ] }, "description": { "type": "string", "example": "High quality tea leaves" }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Product created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Product created successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/products/{id}": { "get": { "tags": [ "Products" ], "summary": "Get product by ID", "description": "Retrieve a specific product with its multi-unit configuration", "operationId": "getProductById", "parameters": [ { "name": "id", "in": "path", "description": "Product ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "Product details", "type": "object" } }, "type": "object" } } } }, "404": { "description": "Product not found" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Products" ], "summary": "Update product", "description": "Update product details including multi-unit configuration", "operationId": "updateProduct", "parameters": [ { "name": "id", "in": "path", "description": "Product ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "description": "Updated product data", "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "Premium Tea Leaves" }, "code": { "type": "string", "example": "PROD001" }, "base_unit": { "type": "string", "example": "kg" }, "supported_units": { "type": "array", "items": { "type": "string" }, "example": [ "kg", "g", "lbs", "oz" ] }, "description": { "type": "string", "example": "Updated description" }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Product updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Product updated successfully" }, "data": { "description": "Updated product details", "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "404": { "description": "Product not found" }, "401": { "description": "Unauthenticated" }, "409": { "description": "Version conflict - resource was modified by another user", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Version conflict detected" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Products" ], "summary": "Delete product", "description": "Remove a product from the system", "operationId": "deleteProduct", "parameters": [ { "name": "id", "in": "path", "description": "Product ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Product deleted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Product deleted successfully" } }, "type": "object" } } } }, "404": { "description": "Product not found" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/products/{id}/current-rate": { "get": { "tags": [ "Products" ], "summary": "Get current product rate", "description": "Retrieve the current rate for a product based on date and unit", "operationId": "getCurrentProductRate", "parameters": [ { "name": "id", "in": "path", "description": "Product ID", "required": true, "schema": { "type": "integer" } }, { "name": "date", "in": "query", "description": "Date to check rate for (defaults to today)", "required": false, "schema": { "type": "string", "format": "date", "example": "2025-12-29" } }, { "name": "unit", "in": "query", "description": "Unit to get rate for (defaults to product base_unit)", "required": false, "schema": { "type": "string", "example": "kg" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "product": { "description": "Product details", "type": "object" }, "rate": { "description": "Current rate details", "type": "object" }, "date": { "type": "string", "example": "2025-12-29" }, "unit": { "type": "string", "example": "kg" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Product not found" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/products/{id}/rate-history": { "get": { "tags": [ "Products" ], "summary": "Get product rate history", "description": "Retrieve the complete rate history for a product, optionally filtered by unit", "operationId": "getProductRateHistory", "parameters": [ { "name": "id", "in": "path", "description": "Product ID", "required": true, "schema": { "type": "integer" } }, { "name": "unit", "in": "query", "description": "Filter history by unit (optional)", "required": false, "schema": { "type": "string", "example": "kg" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "product": { "description": "Product details", "type": "object" }, "unit": { "type": "string", "example": "kg" }, "rates": { "description": "Rate history", "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Product not found" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/rates": { "get": { "tags": [ "Rates" ], "summary": "Get all rates", "description": "Retrieve versioned product rates with historical preservation", "operationId": "getRates", "parameters": [ { "name": "product_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "unit", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "sort_by", "in": "query", "description": "Field to sort by", "required": false, "schema": { "type": "string", "default": "effective_from", "enum": [ "rate", "unit", "effective_from", "effective_to", "version", "created_at", "updated_at" ] } }, { "name": "sort_order", "in": "query", "description": "Sort order", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "Paginated rate list with product details", "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Rates" ], "summary": "Create new rate", "description": "Create a new versioned rate for a product with automatic version incrementing", "operationId": "createRate", "requestBody": { "description": "Rate data with effective date range", "required": true, "content": { "application/json": { "schema": { "required": [ "product_id", "rate", "unit", "effective_from" ], "properties": { "product_id": { "description": "ID of the product", "type": "integer", "example": 1 }, "rate": { "description": "Rate per unit", "type": "number", "format": "float", "example": 250 }, "unit": { "description": "Unit of measurement", "type": "string", "example": "kg" }, "effective_from": { "description": "Rate effective from date", "type": "string", "format": "date", "example": "2025-01-01" }, "effective_to": { "description": "Rate effective to date (optional)", "type": "string", "format": "date", "example": "2025-12-31", "nullable": true }, "is_active": { "description": "Active status", "type": "boolean", "example": true, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Rate created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Rate created successfully" }, "data": { "description": "Rate details with version number", "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/rates/{id}": { "get": { "tags": [ "Rates" ], "summary": "Get rate by ID", "description": "Retrieve a specific rate with product information", "operationId": "getRateById", "parameters": [ { "name": "id", "in": "path", "description": "Rate ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "Rate details", "type": "object" } }, "type": "object" } } } }, "404": { "description": "Rate not found" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Rates" ], "summary": "Update rate", "description": "Update rate details including effective dates and active status", "operationId": "updateRate", "parameters": [ { "name": "id", "in": "path", "description": "Rate ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "description": "Updated rate data", "required": true, "content": { "application/json": { "schema": { "properties": { "product_id": { "type": "integer", "example": 1 }, "rate": { "type": "number", "format": "float", "example": 275 }, "unit": { "type": "string", "example": "kg" }, "effective_from": { "type": "string", "format": "date", "example": "2025-01-01" }, "effective_to": { "type": "string", "format": "date", "example": "2025-12-31", "nullable": true }, "is_active": { "type": "boolean", "example": true, "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Rate updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Rate updated successfully" }, "data": { "description": "Updated rate details", "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "404": { "description": "Rate not found" }, "401": { "description": "Unauthenticated" }, "409": { "description": "Version conflict - resource was modified by another user", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Version conflict detected" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Rates" ], "summary": "Delete rate", "description": "Remove a rate record if it's not used in any collections", "operationId": "deleteRate", "parameters": [ { "name": "id", "in": "path", "description": "Rate ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Rate deleted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Rate deleted successfully" } }, "type": "object" } } } }, "422": { "description": "Cannot delete rate that is used in collections", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Cannot delete rate that is used in collections" } }, "type": "object" } } } }, "404": { "description": "Rate not found" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/reports/summary": { "get": { "tags": [ "Reports" ], "summary": "Get overall system summary", "operationId": "98d48ba832818d097f5ccd0e82b5e3fb", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "totalSuppliers": { "type": "integer", "example": 50 }, "activeSuppliers": { "type": "integer", "example": 45 }, "totalProducts": { "type": "integer", "example": 20 }, "activeProducts": { "type": "integer", "example": 18 }, "totalCollections": { "type": "integer", "example": 1500 }, "totalCollectionAmount": { "type": "number", "format": "float", "example": 125000.5 }, "totalPayments": { "type": "integer", "example": 300 }, "totalPaymentAmount": { "type": "number", "format": "float", "example": 100000 }, "outstandingBalance": { "type": "number", "format": "float", "example": 25000.5 }, "collectionsThisMonth": { "type": "integer", "example": 120 }, "paymentsThisMonth": { "type": "integer", "example": 25 }, "collectionAmountThisMonth": { "type": "number", "format": "float", "example": 10000 }, "paymentAmountThisMonth": { "type": "number", "format": "float", "example": 8000 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/reports/supplier-balances": { "get": { "tags": [ "Reports" ], "summary": "Get supplier balances report", "operationId": "47be52ccd928be71ae1ad502d90d32f6", "parameters": [ { "name": "limit", "in": "query", "description": "Limit number of results", "required": false, "schema": { "type": "integer", "example": 10 } }, { "name": "sort", "in": "query", "description": "Sort by balance (asc or desc)", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "example": "desc" } } ], "responses": { "200": { "description": "Supplier balances retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "supplier_id": { "type": "integer", "example": 1 }, "supplier_name": { "type": "string", "example": "John Supplier" }, "supplier_code": { "type": "string", "example": "SUP001" }, "total_collections": { "type": "number", "format": "float", "example": 50000 }, "total_payments": { "type": "number", "format": "float", "example": 45000 }, "balance": { "type": "number", "format": "float", "example": 5000 }, "collection_count": { "type": "integer", "example": 50 }, "payment_count": { "type": "integer", "example": 10 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/reports/collections-summary": { "get": { "tags": [ "Reports" ], "summary": "Get collections summary by date range", "operationId": "3d2e945f3571a3e78432013dc525cddc", "parameters": [ { "name": "start_date", "in": "query", "description": "Start date (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date", "example": "2025-01-01" } }, { "name": "end_date", "in": "query", "description": "End date (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date", "example": "2025-12-31" } }, { "name": "supplier_id", "in": "query", "description": "Filter by supplier ID", "required": false, "schema": { "type": "integer" } }, { "name": "product_id", "in": "query", "description": "Filter by product ID", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Collections summary retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "summary": { "properties": { "total_count": { "type": "integer", "example": 150 }, "total_amount": { "type": "number", "format": "float", "example": 75000 }, "total_quantity": { "type": "number", "format": "float", "example": 2500.5 } }, "type": "object" }, "by_product": { "type": "array", "items": { "properties": { "product_id": { "type": "integer" }, "product_name": { "type": "string" }, "count": { "type": "integer" }, "total_quantity": { "type": "number", "format": "float" }, "total_amount": { "type": "number", "format": "float" } }, "type": "object" } }, "by_supplier": { "type": "array", "items": { "properties": { "supplier_id": { "type": "integer" }, "supplier_name": { "type": "string" }, "supplier_code": { "type": "string" }, "count": { "type": "integer" }, "total_quantity": { "type": "number", "format": "float" }, "total_amount": { "type": "number", "format": "float" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/reports/payments-summary": { "get": { "tags": [ "Reports" ], "summary": "Get payments summary by date range", "operationId": "bdef2121fdcd2f2cc2dd902107aab94e", "parameters": [ { "name": "start_date", "in": "query", "description": "Start date (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "description": "End date (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "supplier_id", "in": "query", "description": "Filter by supplier ID", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payments summary retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "summary": { "properties": { "total_count": { "type": "integer", "example": 50 }, "total_amount": { "type": "number", "format": "float", "example": 50000 } }, "type": "object" }, "by_type": { "type": "array", "items": { "properties": { "type": { "type": "string", "example": "partial" }, "count": { "type": "integer", "example": 30 }, "total_amount": { "type": "number", "format": "float", "example": 30000 } }, "type": "object" } }, "by_supplier": { "type": "array", "items": { "properties": { "supplier_id": { "type": "integer" }, "supplier_name": { "type": "string" }, "supplier_code": { "type": "string" }, "count": { "type": "integer" }, "total_amount": { "type": "number", "format": "float" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/reports/product-performance": { "get": { "tags": [ "Reports" ], "summary": "Get product performance report", "operationId": "198c06acaafd9998e52dd6f3eddccdc4", "parameters": [ { "name": "start_date", "in": "query", "description": "Start date (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "description": "End date (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Product performance retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "product_id": { "type": "integer", "example": 1 }, "product_name": { "type": "string", "example": "Tea Leaves" }, "product_code": { "type": "string", "example": "PROD001" }, "collection_count": { "type": "integer", "example": 150 }, "total_quantity": { "type": "number", "format": "float", "example": 2500.5 }, "total_amount": { "type": "number", "format": "float", "example": 75000 }, "unique_suppliers": { "type": "integer", "example": 5 }, "avg_rate": { "type": "number", "format": "float", "example": 30 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/reports/financial-summary": { "get": { "tags": [ "Reports" ], "summary": "Get comprehensive financial summary", "operationId": "ec02c5b782e0054e682f0de9fb448666", "parameters": [ { "name": "start_date", "in": "query", "description": "Start date (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "description": "End date (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Financial summary retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "summary": { "properties": { "total_collections": { "type": "number", "format": "float", "example": 125000 }, "total_payments": { "type": "number", "format": "float", "example": 100000 }, "net_balance": { "type": "number", "format": "float", "example": 25000 } }, "type": "object" }, "monthly_breakdown": { "type": "array", "items": { "properties": { "month": { "type": "string", "example": "2025-01" }, "collections": { "type": "number", "format": "float", "example": 10000 }, "payments": { "type": "number", "format": "float", "example": 8000 }, "net": { "type": "number", "format": "float", "example": 2000 } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/reports/summary/pdf": { "get": { "tags": [ "Reports" ], "summary": "Download system summary report as PDF", "operationId": "a9ce1335ce254b2ac3ced1903ab0f779", "responses": { "200": { "description": "PDF downloaded successfully", "content": { "application/pdf": {} } }, "401": { "description": "Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/reports/supplier-balances/pdf": { "get": { "tags": [ "Reports" ], "summary": "Download supplier balances report as PDF", "operationId": "34be1cf8970afb19fe18bbbcbcbe75bf", "parameters": [ { "name": "limit", "in": "query", "description": "Limit number of results", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "PDF downloaded successfully", "content": { "application/pdf": {} } }, "401": { "description": "Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/reports/collections-summary/pdf": { "get": { "tags": [ "Reports" ], "summary": "Download collections summary as PDF", "operationId": "04b7eabf9ab7c3fde33f9b829adb75d2", "responses": { "200": { "description": "PDF downloaded successfully", "content": { "application/pdf": {} } }, "401": { "description": "Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/reports/payments-summary/pdf": { "get": { "tags": [ "Reports" ], "summary": "Download payments summary as PDF", "operationId": "a4d9a370708e452e18b23b21a4d1475c", "responses": { "200": { "description": "PDF downloaded successfully", "content": { "application/pdf": {} } }, "401": { "description": "Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/reports/product-performance/pdf": { "get": { "tags": [ "Reports" ], "summary": "Download product performance report as PDF", "operationId": "47393a7736162e7a56ff31cbad6409fa", "responses": { "200": { "description": "PDF downloaded successfully", "content": { "application/pdf": {} } }, "401": { "description": "Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/reports/financial-summary/pdf": { "get": { "tags": [ "Reports" ], "summary": "Download financial summary as PDF", "operationId": "e514c7f1a41794b2ee76485c96eea346", "responses": { "200": { "description": "PDF downloaded successfully", "content": { "application/pdf": {} } }, "401": { "description": "Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/roles": { "get": { "tags": [ "Roles" ], "summary": "Get all roles", "description": "Retrieve a paginated list of roles with user count", "operationId": "getRoles", "parameters": [ { "name": "search", "in": "query", "description": "Search by name or display_name", "required": false, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "description": "Results per page", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "sort_by", "in": "query", "description": "Field to sort by", "required": false, "schema": { "type": "string", "default": "created_at", "enum": [ "name", "display_name", "created_at", "updated_at" ] } }, { "name": "sort_order", "in": "query", "description": "Sort order", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "Paginated role list with user counts", "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Roles" ], "summary": "Create new role", "description": "Create a new role with permissions", "operationId": "createRole", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "display_name" ], "properties": { "name": { "type": "string", "example": "manager" }, "display_name": { "type": "string", "example": "Manager" }, "description": { "type": "string", "example": "Role for managers" }, "permissions": { "type": "array", "items": { "type": "string" }, "example": [ "view_reports", "manage_collections" ] } }, "type": "object" } } } }, "responses": { "201": { "description": "Role created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Role created successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/roles/{id}": { "get": { "tags": [ "Roles" ], "summary": "Get role by ID", "description": "Retrieve a single role with user count", "operationId": "getRoleById", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Role not found" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Roles" ], "summary": "Update role", "description": "Update role information and permissions", "operationId": "updateRole", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "supervisor" }, "display_name": { "type": "string", "example": "Supervisor" }, "description": { "type": "string", "example": "Role for supervisors" }, "permissions": { "type": "array", "items": { "type": "string" }, "example": [ "view_reports", "approve_collections" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Role updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Role updated successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Role not found" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Roles" ], "summary": "Delete role", "description": "Delete a role (only if no users are assigned)", "operationId": "deleteRole", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Role deleted", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Role deleted successfully" } }, "type": "object" } } } }, "422": { "description": "Cannot delete role with active users", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Cannot delete role with active users" } }, "type": "object" } } } }, "404": { "description": "Role not found" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/suppliers": { "get": { "tags": [ "Suppliers" ], "summary": "Get all suppliers", "description": "Retrieve a paginated list of suppliers with optional filtering", "operationId": "getSuppliers", "parameters": [ { "name": "is_active", "in": "query", "description": "Filter by active status", "required": false, "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "description": "Search by name, code, or region", "required": false, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "description": "Results per page", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "sort_by", "in": "query", "description": "Field to sort by", "required": false, "schema": { "type": "string", "default": "created_at", "enum": [ "name", "code", "region", "created_at", "updated_at" ] } }, { "name": "sort_order", "in": "query", "description": "Sort order", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "Paginated supplier list", "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Suppliers" ], "summary": "Create new supplier", "description": "Create a new supplier with profile details", "operationId": "createSupplier", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "code" ], "properties": { "name": { "type": "string", "example": "ABC Tea Suppliers" }, "code": { "type": "string", "example": "SUP001" }, "region": { "type": "string", "example": "Central" }, "contact_person": { "type": "string", "example": "John Doe" }, "phone": { "type": "string", "example": "+94771234567" }, "email": { "type": "string", "example": "supplier@example.com" }, "address": { "type": "string", "example": "123 Main St" }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Supplier created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Supplier created successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/suppliers/{id}": { "get": { "tags": [ "Suppliers" ], "summary": "Get supplier by ID", "description": "Retrieve a specific supplier with profile details", "operationId": "getSupplierById", "parameters": [ { "name": "id", "in": "path", "description": "Supplier ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "Supplier details", "type": "object" } }, "type": "object" } } } }, "404": { "description": "Supplier not found" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Suppliers" ], "summary": "Update supplier", "description": "Update supplier profile details with version control", "operationId": "updateSupplier", "parameters": [ { "name": "id", "in": "path", "description": "Supplier ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "description": "Updated supplier data", "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "ABC Tea Suppliers Ltd" }, "code": { "type": "string", "example": "SUP001" }, "region": { "type": "string", "example": "Western" }, "contact_person": { "type": "string", "example": "Jane Smith" }, "phone": { "type": "string", "example": "+94777654321" }, "email": { "type": "string", "example": "updated@example.com" }, "address": { "type": "string", "example": "456 New Address" }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Supplier updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Supplier updated successfully" }, "data": { "description": "Updated supplier details", "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "404": { "description": "Supplier not found" }, "401": { "description": "Unauthenticated" }, "409": { "description": "Version conflict - resource was modified by another user", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Version conflict detected" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Suppliers" ], "summary": "Delete supplier", "description": "Remove a supplier from the system", "operationId": "deleteSupplier", "parameters": [ { "name": "id", "in": "path", "description": "Supplier ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Supplier deleted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Supplier deleted successfully" } }, "type": "object" } } } }, "404": { "description": "Supplier not found" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/suppliers/{id}/balance": { "get": { "tags": [ "Suppliers" ], "summary": "Get supplier balance", "description": "Calculate and retrieve supplier balance based on collections and payments", "operationId": "getSupplierBalance", "parameters": [ { "name": "id", "in": "path", "description": "Supplier ID", "required": true, "schema": { "type": "integer" } }, { "name": "start_date", "in": "query", "description": "Start date for balance calculation", "required": false, "schema": { "type": "string", "format": "date", "example": "2025-01-01" } }, { "name": "end_date", "in": "query", "description": "End date for balance calculation", "required": false, "schema": { "type": "string", "format": "date", "example": "2025-12-31" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "supplier": { "description": "Supplier details", "type": "object" }, "total_collected": { "description": "Total amount collected", "type": "number", "format": "float", "example": 125000 }, "total_paid": { "description": "Total amount paid", "type": "number", "format": "float", "example": 100000 }, "balance": { "description": "Outstanding balance", "type": "number", "format": "float", "example": 25000 }, "period": { "properties": { "start_date": { "type": "string", "nullable": true }, "end_date": { "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Supplier not found" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/suppliers/{id}/collections": { "get": { "tags": [ "Suppliers" ], "summary": "Get supplier collections", "description": "Retrieve all collections for a specific supplier with date filtering", "operationId": "getSupplierCollections", "parameters": [ { "name": "id", "in": "path", "description": "Supplier ID", "required": true, "schema": { "type": "integer" } }, { "name": "start_date", "in": "query", "description": "Filter collections from this date", "required": false, "schema": { "type": "string", "format": "date", "example": "2025-01-01" } }, { "name": "end_date", "in": "query", "description": "Filter collections until this date", "required": false, "schema": { "type": "string", "format": "date", "example": "2025-12-31" } }, { "name": "per_page", "in": "query", "description": "Results per page", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "sort_by", "in": "query", "description": "Field to sort by", "required": false, "schema": { "type": "string", "default": "collection_date", "enum": [ "collection_date", "quantity", "total_amount" ] } }, { "name": "sort_order", "in": "query", "description": "Sort order", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "Paginated collections with product, user, and rate details", "type": "object" } }, "type": "object" } } } }, "404": { "description": "Supplier not found" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/suppliers/{id}/payments": { "get": { "tags": [ "Suppliers" ], "summary": "Get supplier payments", "description": "Retrieve all payments for a specific supplier with date filtering", "operationId": "getSupplierPayments", "parameters": [ { "name": "id", "in": "path", "description": "Supplier ID", "required": true, "schema": { "type": "integer" } }, { "name": "start_date", "in": "query", "description": "Filter payments from this date", "required": false, "schema": { "type": "string", "format": "date", "example": "2025-01-01" } }, { "name": "end_date", "in": "query", "description": "Filter payments until this date", "required": false, "schema": { "type": "string", "format": "date", "example": "2025-12-31" } }, { "name": "per_page", "in": "query", "description": "Results per page", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "sort_by", "in": "query", "description": "Field to sort by", "required": false, "schema": { "type": "string", "default": "payment_date", "enum": [ "payment_date", "amount", "type" ] } }, { "name": "sort_order", "in": "query", "description": "Sort order", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "Paginated payments with user details", "type": "object" } }, "type": "object" } } } }, "404": { "description": "Supplier not found" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/users": { "get": { "tags": [ "Users" ], "summary": "Get all users", "description": "Retrieve a paginated list of users with role information", "operationId": "getUsers", "parameters": [ { "name": "is_active", "in": "query", "description": "Filter by active status", "required": false, "schema": { "type": "boolean" } }, { "name": "role_id", "in": "query", "description": "Filter by role ID", "required": false, "schema": { "type": "integer" } }, { "name": "search", "in": "query", "description": "Search by name or email", "required": false, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "description": "Results per page", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "sort_by", "in": "query", "description": "Field to sort by", "required": false, "schema": { "type": "string", "default": "created_at", "enum": [ "name", "email", "created_at", "updated_at" ] } }, { "name": "sort_order", "in": "query", "description": "Sort order", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "Paginated user list", "properties": { "current_page": { "type": "integer", "example": 1 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john@example.com" }, "role_id": { "type": "integer", "example": 2 }, "is_active": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "role": { "properties": { "id": { "type": "integer", "example": 2 }, "name": { "type": "string", "example": "manager" }, "display_name": { "type": "string", "example": "Manager" } }, "type": "object" } }, "type": "object" } }, "first_page_url": { "type": "string" }, "from": { "type": "integer" }, "last_page": { "type": "integer" }, "last_page_url": { "type": "string" }, "next_page_url": { "type": "string", "nullable": true }, "path": { "type": "string" }, "per_page": { "type": "integer", "example": 15 }, "prev_page_url": { "type": "string", "nullable": true }, "to": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Users" ], "summary": "Create new user", "description": "Create a new user with role assignment", "operationId": "createUser", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "password", "password_confirmation", "role_id" ], "properties": { "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "user@example.com" }, "password": { "type": "string", "example": "password123" }, "password_confirmation": { "type": "string", "example": "password123" }, "role_id": { "type": "integer", "example": 2 }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "User created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "User created successfully" }, "data": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "user@example.com" }, "role_id": { "type": "integer", "example": 2 }, "is_active": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "role": { "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/users/{id}": { "get": { "tags": [ "Users" ], "summary": "Get user by ID", "description": "Retrieve a single user with role information", "operationId": "getUserById", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john@example.com" }, "role_id": { "type": "integer", "example": 2 }, "is_active": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "role": { "properties": { "id": { "type": "integer", "example": 2 }, "name": { "type": "string", "example": "manager" }, "display_name": { "type": "string", "example": "Manager" }, "description": { "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "User not found" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Users" ], "summary": "Update user", "description": "Update user information and role", "operationId": "updateUser", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "Jane Smith" }, "email": { "type": "string", "example": "jane.smith@example.com" }, "password": { "type": "string", "example": "newpassword123" }, "password_confirmation": { "type": "string", "example": "newpassword123" }, "role_id": { "type": "integer", "example": 2 }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "User updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "User updated successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "User not found" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Users" ], "summary": "Delete user", "description": "Soft delete a user", "operationId": "deleteUser", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "User deleted", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "User deleted successfully" } }, "type": "object" } } } }, "404": { "description": "User not found" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "responses": { "RateLimitExceeded": { "description": "Rate limit exceeded - Too many requests", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Too Many Requests" } }, "type": "object" } } } }, "Unauthenticated": { "description": "Authentication required", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "description": "JWT Bearer Token authentication. Include the token in the Authorization header as: Bearer {token}", "bearerFormat": "JWT", "scheme": "bearer" } } }, "tags": [ { "name": "Reports", "description": "Comprehensive reporting and analytics endpoints" }, { "name": "Authentication", "description": "User authentication and authorization endpoints" }, { "name": "Users", "description": "User management operations" }, { "name": "Roles", "description": "Role management for RBAC" }, { "name": "Suppliers", "description": "Supplier management with multi-unit tracking" }, { "name": "Products", "description": "Product management with multi-unit support" }, { "name": "Rates", "description": "Versioned rate management for products" }, { "name": "Collections", "description": "Daily collection tracking with multi-unit quantities" }, { "name": "Payments", "description": "Payment management with advance, partial, and full payment support" } ] }