{ "openapi": "3.0.0", "info": { "title": "ERPly REST API", "description": "ERPly RESTful API for managing business operations including customers, vendors, products, invoices, sales orders, purchase orders, payments, accounting, HR, inventory, and more.", "contact": { "name": "ERPly Support", "email": "support@erply.com" }, "version": "1.0.0" }, "servers": [ { "url": "http://localhost:8000/api/v1", "description": "Development (local)" }, { "url": "https://api.erply.sa/api/v1", "description": "Production" } ], "paths": { "/accounts": { "get": { "tags": [ "Accounts" ], "summary": "List chart of accounts", "description": "Returns a paginated list of accounts with optional search and filtering.", "operationId": "4f73d966e784535840894c216e31b991", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Search by name or code", "required": false, "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "Filter by account type", "required": false, "schema": { "type": "string", "enum": [ "asset", "liability", "equity", "income", "expense" ] } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "code" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "asc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of accounts", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Accounts" ], "summary": "Create account", "description": "Creates a new account in the chart of accounts.", "operationId": "06f31bd116bd6d2e6b46eb4ddf841322", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "code", "name", "type", "normal_balance" ], "properties": { "code": { "type": "string", "example": "1010", "maxLength": 50 }, "name": { "type": "string", "example": "Cash", "maxLength": 255 }, "type": { "type": "string", "example": "asset", "enum": [ "asset", "liability", "equity", "income", "expense" ] }, "sub_type": { "type": "string", "nullable": true, "enum": [ "customer", "vendor", "cash", "bank" ] }, "normal_balance": { "type": "string", "example": "debit", "enum": [ "debit", "credit" ] }, "parent_id": { "type": "integer", "example": null, "nullable": true }, "is_reconcilable": { "type": "boolean", "example": false }, "is_active": { "type": "boolean", "example": true }, "description": { "type": "string", "nullable": true, "maxLength": 1000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Account created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/Account" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/accounts/{id}": { "get": { "tags": [ "Accounts" ], "summary": "Get account by ID", "description": "Returns a single account record.", "operationId": "d7879531cbed34bcb21c7dfdbac6fa04", "parameters": [ { "name": "id", "in": "path", "description": "Account ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Account details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Account" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Accounts" ], "summary": "Update account", "description": "Updates an existing account record.", "operationId": "f2f5b87820e4e5c3dd7576dfa6a402ad", "parameters": [ { "name": "id", "in": "path", "description": "Account ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "code", "name", "type", "normal_balance" ], "properties": { "code": { "type": "string", "maxLength": 50 }, "name": { "type": "string", "maxLength": 255 }, "type": { "type": "string", "enum": [ "asset", "liability", "equity", "income", "expense" ] }, "sub_type": { "type": "string", "nullable": true, "enum": [ "customer", "vendor", "cash", "bank" ] }, "normal_balance": { "type": "string", "enum": [ "debit", "credit" ] }, "parent_id": { "type": "integer", "nullable": true }, "is_reconcilable": { "type": "boolean" }, "is_active": { "type": "boolean" }, "description": { "type": "string", "nullable": true, "maxLength": 1000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Account updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Account" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Accounts" ], "summary": "Delete account", "description": "Soft-deletes an account record.", "operationId": "624aba553373a9b6455332739d3c623a", "parameters": [ { "name": "id", "in": "path", "description": "Account ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Account deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/accounts/{id}/balance": { "get": { "tags": [ "Accounts" ], "summary": "Get account balance", "description": "Returns the current computed balance for the account.", "operationId": "1b3c36161ff721a8900e4fd0c73d23eb", "parameters": [ { "name": "id", "in": "path", "description": "Account ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Account balance", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "properties": { "account_id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "1010" }, "name": { "type": "string", "example": "Cash" }, "normal_balance": { "type": "string", "example": "debit", "enum": [ "debit", "credit" ] }, "balance": { "type": "number", "format": "float", "example": 15000 } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/accounts/{id}/transactions": { "get": { "tags": [ "Accounts" ], "summary": "Get account transactions", "description": "Returns a paginated list of transactions for the account.", "operationId": "bc23bd399a0414f52d6ac28e5aca6ab0", "parameters": [ { "name": "id", "in": "path", "description": "Account ID", "required": true, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated account transactions", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "journal_entry_id": { "type": "integer", "example": 5 }, "journal_entry_ref": { "type": "string", "example": "JE-ABC12345", "nullable": true }, "type": { "type": "string", "example": "debit", "enum": [ "debit", "credit" ] }, "amount": { "type": "number", "format": "float", "example": 1000 }, "currency_id": { "type": "integer", "example": 1, "nullable": true }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/accounting-periods": { "get": { "tags": [ "Accounting Periods" ], "summary": "List accounting periods", "description": "Returns a paginated list of accounting period locks. Filter by period string (YYYY-MM) or lock status.", "operationId": "14f5cbcfe06f5c74ce2fe5a68528e18f", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100 } }, { "name": "period", "in": "query", "description": "Filter by period (YYYY-MM)", "required": false, "schema": { "type": "string" } }, { "name": "lock_type", "in": "query", "description": "Filter by lock type", "required": false, "schema": { "type": "string", "enum": [ "soft", "hard" ] } }, { "name": "active", "in": "query", "description": "Filter by active status (1=locked, 0=unlocked)", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "default": "period" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of accounting periods", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Accounting Periods" ], "summary": "Create (lock) an accounting period", "description": "Creates a period lock record for a given YYYY-MM period.", "operationId": "19009bfda27e756b022c4bda2652722a", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "period", "lock_type" ], "properties": { "period": { "description": "Period in YYYY-MM format", "type": "string", "example": "2025-03" }, "lock_type": { "type": "string", "example": "hard", "enum": [ "soft", "hard" ] }, "reason": { "type": "string", "example": "Month-end close", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Period lock created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/accounting-periods/{id}": { "get": { "tags": [ "Accounting Periods" ], "summary": "Get accounting period by ID", "description": "Returns a single accounting period lock record.", "operationId": "80ffc7454d3e32f99fb211eeb79116ba", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Accounting period details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Accounting Periods" ], "summary": "Update accounting period lock", "description": "Updates the lock_type or reason of an existing period lock.", "operationId": "241f24c6d0d374b1d705d12395bf51ae", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "lock_type": { "type": "string", "enum": [ "soft", "hard" ] }, "reason": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Period lock updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/accounting-periods/{id}/lock": { "post": { "tags": [ "Accounting Periods" ], "summary": "Lock an accounting period", "description": "Sets the period lock as active (clears unlocked_at). Useful to re-lock a previously unlocked period.", "operationId": "574a7f7c79ef6b5ebe845623451d0f14", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "lock_type": { "type": "string", "example": "hard", "enum": [ "soft", "hard" ] }, "reason": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Period locked", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Period is already locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/accounting-periods/{id}/unlock": { "post": { "tags": [ "Accounting Periods" ], "summary": "Unlock an accounting period", "description": "Unlocks a locked period by setting unlocked_at and unlocked_by.", "operationId": "c195ac25adeefea0fb73a79655cf76f2", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Period unlocked", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Period is already unlocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/advance-payments": { "get": { "tags": [ "Advance Payments" ], "summary": "List advance payments", "description": "Returns a paginated list of advance payments (is_advance=true). Filter by customer_id, vendor_id, or status.", "operationId": "7bbd84f66fba31e41a05d33b802ccb02", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100 } }, { "name": "customer_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "vendor_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "posted", "partially_applied", "fully_applied" ] } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "default": "payment_date" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of advance payments", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Advance Payments" ], "summary": "Create advance payment", "description": "Creates an advance payment record and posts the journal entry via AdvancePaymentService.", "operationId": "d321cb693511e879321825729d72ff8a", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "entity_type", "entity_id", "amount", "payment_date", "method" ], "properties": { "entity_type": { "type": "string", "example": "customer", "enum": [ "customer", "vendor" ] }, "entity_id": { "type": "integer", "example": 5 }, "amount": { "type": "number", "format": "float", "example": 1000 }, "payment_date": { "type": "string", "format": "date", "example": "2025-03-15" }, "method": { "type": "string", "example": "bank_transfer", "enum": [ "cash", "bank_transfer", "cheque", "credit_card" ] }, "reference": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "currency_code": { "type": "string", "example": "USD", "nullable": true }, "exchange_rate": { "type": "number", "nullable": true }, "bank_account_id": { "type": "integer", "nullable": true }, "advance_account_id": { "type": "integer", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Advance payment created and journal entry posted", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation or accounting error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/advance-payments/{id}": { "get": { "tags": [ "Advance Payments" ], "summary": "Get advance payment by ID", "description": "Returns a single advance payment record.", "operationId": "710acf1a5fd2490f5e74d58588a1f43f", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Advance payment details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/advance-payments/{id}/apply": { "post": { "tags": [ "Advance Payments" ], "summary": "Apply advance to invoice", "description": "Applies a posted customer advance to an open invoice. Creates the clearing journal entry via AdvancePaymentService.", "operationId": "fb262cbc37469a5df2c2040da9fa8482", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "invoice_id", "amount_to_apply" ], "properties": { "invoice_id": { "type": "integer", "example": 42 }, "amount_to_apply": { "type": "number", "format": "float", "example": 500 } }, "type": "object" } } } }, "responses": { "200": { "description": "Advance applied to invoice", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Insufficient advance balance or invalid state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/bank-statements": { "get": { "tags": [ "Bank Statements" ], "summary": "List bank statements", "description": "Returns a paginated list of bank statements with optional filtering.", "operationId": "f187bcbcab5c11b8d5edd7c6c2e1075e", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "account_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "reconciled" ] } } ], "responses": { "200": { "description": "Paginated list of bank statements" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Bank Statements" ], "summary": "Create bank statement", "operationId": "0e3aae68c682e6cb7e9ba975a41ae407", "responses": { "201": { "description": "Bank statement created" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/bank-statements/{id}": { "get": { "tags": [ "Bank Statements" ], "summary": "Get bank statement by ID", "operationId": "03557c6ece3cf7550a7f8fd351f798d0", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Bank statement with lines" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Bank Statements" ], "summary": "Update bank statement", "operationId": "9383e78ecf43b12fbafdb0bf54ea7071", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Bank statement updated" }, "422": { "description": "Not in draft status or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Bank Statements" ], "summary": "Delete bank statement", "operationId": "5f518504df7801990fd62528cc34cd74", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted" }, "422": { "description": "Not in draft status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/bank-statements/{id}/lines": { "get": { "tags": [ "Bank Statements" ], "summary": "List lines for a bank statement", "operationId": "31caab5f776ed34d16da19435e1b465a", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Bank statement lines" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Bank Statements" ], "summary": "Add a line to a bank statement", "operationId": "40362606d5634996eb8c164ac5841e54", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "201": { "description": "Line added" }, "422": { "description": "Not in draft status or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/bank-statements/{id}/reconcile": { "post": { "tags": [ "Bank Statements" ], "summary": "Reconcile a bank statement", "description": "Transitions a draft bank statement to reconciled status.", "operationId": "e05840f9ef544fb76fb07d92b64cf903", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Bank statement reconciled" }, "422": { "description": "Not in draft status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/bills": { "get": { "tags": [ "Bills" ], "summary": "List bills", "description": "Returns a paginated list of vendor bills with optional search and filtering.", "operationId": "7073533ad5b294b607893f2f4c6e078b", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Search by reference or vendor name", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "draft", "submitted", "approved", "paid", "cancelled" ] } }, { "name": "vendor_id", "in": "query", "description": "Filter by vendor ID", "required": false, "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of bills", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Bill" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Bills" ], "summary": "Create bill", "description": "Creates a new vendor bill.", "operationId": "089763a39c9b5a534f913afccdcd5808", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "vendor_id" ], "properties": { "vendor_id": { "type": "integer", "example": 1 }, "purchase_order_id": { "type": "integer", "example": 1, "nullable": true }, "currency_id": { "type": "integer", "example": 1, "nullable": true }, "exchange_rate": { "type": "number", "format": "float", "example": 1, "nullable": true }, "bill_date": { "type": "string", "format": "date", "example": "2024-01-15", "nullable": true }, "due_date": { "type": "string", "format": "date", "example": "2024-02-15", "nullable": true }, "reference": { "type": "string", "nullable": true, "maxLength": 255 }, "vendor_reference": { "type": "string", "example": "VND-INV-123", "nullable": true, "maxLength": 255 }, "subtotal": { "type": "number", "format": "float", "example": 500, "nullable": true }, "tax_amount": { "type": "number", "format": "float", "example": 75, "nullable": true }, "total": { "type": "number", "format": "float", "example": 575, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Bill created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/Bill" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/bills/{id}": { "get": { "tags": [ "Bills" ], "summary": "Get bill by ID", "description": "Returns a single vendor bill record.", "operationId": "9a052b9bc096e8f23d690d5a6f198ac1", "parameters": [ { "name": "id", "in": "path", "description": "Bill ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Bill details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Bill" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Bills" ], "summary": "Update bill", "description": "Updates an existing vendor bill.", "operationId": "168a5c16ae1298ed166a164039087b30", "parameters": [ { "name": "id", "in": "path", "description": "Bill ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "vendor_id" ], "properties": { "vendor_id": { "type": "integer", "example": 1 }, "purchase_order_id": { "type": "integer", "nullable": true }, "currency_id": { "type": "integer", "nullable": true }, "exchange_rate": { "type": "number", "format": "float", "nullable": true }, "bill_date": { "type": "string", "format": "date", "nullable": true }, "due_date": { "type": "string", "format": "date", "nullable": true }, "reference": { "type": "string", "nullable": true, "maxLength": 255 }, "vendor_reference": { "type": "string", "nullable": true, "maxLength": 255 }, "subtotal": { "type": "number", "format": "float", "nullable": true }, "tax_amount": { "type": "number", "format": "float", "nullable": true }, "total": { "type": "number", "format": "float", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Bill updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Bill" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Bills" ], "summary": "Delete bill", "description": "Soft-deletes a vendor bill.", "operationId": "49bfd6ae65bc771737377a997f0d6074", "parameters": [ { "name": "id", "in": "path", "description": "Bill ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Bill deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/bills/{id}/submit": { "post": { "tags": [ "Bills" ], "summary": "Submit bill for approval", "description": "Transitions a draft bill to submitted status.", "operationId": "60dffe1818cbe95591da7b36ae7db954", "parameters": [ { "name": "id", "in": "path", "description": "Bill ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Bill submitted", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Bill" } }, "type": "object" } } } }, "422": { "description": "Bill is not in draft status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/bills/{id}/post": { "post": { "tags": [ "Bills" ], "summary": "Post bill", "description": "Transitions a submitted or approved bill to posted status.", "operationId": "155c22f6b2a6701d57108c2e7053fedf", "parameters": [ { "name": "id", "in": "path", "description": "Bill ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Bill posted", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Bill" } }, "type": "object" } } } }, "422": { "description": "Bill cannot be posted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/bills/{id}/cancel": { "post": { "tags": [ "Bills" ], "summary": "Cancel bill", "description": "Cancels a bill that is not yet posted or already cancelled.", "operationId": "07cd748b1f73b900f680676e80ce89f4", "parameters": [ { "name": "id", "in": "path", "description": "Bill ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "cancellation_reason": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Bill cancelled", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Bill" } }, "type": "object" } } } }, "422": { "description": "Bill cannot be cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/bills/{id}/lines": { "get": { "tags": [ "Bills" ], "summary": "Get bill financial summary", "description": "Returns financial summary fields for the bill (subtotal, tax, total, paid, due).", "operationId": "3ced2c4f15cad6752bd4474f8b840694", "parameters": [ { "name": "id", "in": "path", "description": "Bill ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Bill financial summary", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "properties": { "subtotal": { "type": "number", "format": "float" }, "tax_amount": { "type": "number", "format": "float" }, "total": { "type": "number", "format": "float" }, "amount_paid": { "type": "number", "format": "float" }, "amount_due": { "type": "number", "format": "float" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/budgets": { "get": { "tags": [ "Budgets" ], "summary": "List budgets", "description": "Returns a paginated list of budgets with optional filtering.", "operationId": "2be5e08ae9134b85981bb4d2b451149d", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "fiscal_year_id", "in": "query", "description": "Filter by fiscal year", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "draft", "approved" ] } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of budgets", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Budget" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Budgets" ], "summary": "Create budget", "description": "Creates a new budget with optional lines. Status is set to draft.", "operationId": "70f7827e9d5abd504362192d555b6e5e", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "fiscal_year_id", "name" ], "properties": { "fiscal_year_id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "FY2025 Budget", "maxLength": 255 }, "type": { "type": "string", "nullable": true, "maxLength": 50 }, "notes": { "type": "string", "nullable": true, "maxLength": 1000 }, "lines": { "type": "array", "items": { "properties": { "account_id": { "type": "integer", "example": 1 }, "cost_center_id": { "type": "integer", "nullable": true }, "amount": { "type": "number", "format": "float", "example": 10000 }, "notes": { "type": "string", "nullable": true, "maxLength": 500 } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Budget created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/Budget" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/budgets/{id}": { "get": { "tags": [ "Budgets" ], "summary": "Get budget by ID", "description": "Returns a single budget record with its lines.", "operationId": "e1a0a1b3633b2e1a5281302153a65d1e", "parameters": [ { "name": "id", "in": "path", "description": "Budget ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Budget details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Budget" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Budgets" ], "summary": "Update budget", "description": "Updates an existing budget. Only allowed if status is draft. Syncs lines (deletes existing, creates new).", "operationId": "d087af00eed6cd821e6644cb0bfc6d9a", "parameters": [ { "name": "id", "in": "path", "description": "Budget ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "fiscal_year_id", "name" ], "properties": { "fiscal_year_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "type": { "type": "string", "nullable": true, "maxLength": 50 }, "notes": { "type": "string", "nullable": true, "maxLength": 1000 }, "lines": { "type": "array", "items": { "properties": { "account_id": { "type": "integer" }, "cost_center_id": { "type": "integer", "nullable": true }, "amount": { "type": "number", "format": "float" }, "notes": { "type": "string", "nullable": true, "maxLength": 500 } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Budget updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Budget" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Budgets" ], "summary": "Delete budget", "description": "Soft-deletes a budget. Only allowed if status is draft.", "operationId": "71e10a6546e85f328c7b263300d43b4e", "parameters": [ { "name": "id", "in": "path", "description": "Budget ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Budget deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/budgets/{id}/approve": { "post": { "tags": [ "Budgets" ], "summary": "Approve budget", "description": "Sets the budget status to approved. Only allowed if currently in draft status.", "operationId": "5e2fefdcc1fa79359995e327f78d9187", "parameters": [ { "name": "id", "in": "path", "description": "Budget ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Budget approved", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Budget" } }, "type": "object" } } } }, "422": { "description": "Budget is not in draft status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/budgets/{id}/submit": { "post": { "tags": [ "Budgets" ], "summary": "Submit budget for approval", "description": "Transitions a draft budget to submitted status for review.", "operationId": "f2e6a5a2d9cc31c6287c096a087b4900", "parameters": [ { "name": "id", "in": "path", "description": "Budget ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Budget submitted", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Budget" } }, "type": "object" } } } }, "422": { "description": "Budget is not in draft status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/canned-replies": { "get": { "tags": [ "Canned Replies" ], "summary": "List canned replies", "operationId": "f4bc4afdb7c3e70a485161e08262d4b9", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "List of canned replies" } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Canned Replies" ], "summary": "Create a canned reply", "operationId": "c491c1690ed00e317513252b927ba942", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title", "body" ], "properties": { "title": { "type": "string" }, "body": { "type": "string" }, "category": { "type": "string", "nullable": true }, "shortcut": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Created" }, "422": { "description": "Validation error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/canned-replies/{id}": { "get": { "tags": [ "Canned Replies" ], "summary": "Get canned reply by ID", "operationId": "9074c5d7bde7082ac6fc3e21c9524907", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Canned reply details" }, "404": { "description": "Not found" } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Canned Replies" ], "summary": "Update a canned reply", "operationId": "1dd09727d2ac3af6d3c70da87abdd8bd", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CannedReplyRequest" } } } }, "responses": { "200": { "description": "Updated" }, "422": { "description": "Validation error" } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Canned Replies" ], "summary": "Delete a canned reply", "operationId": "8c022386510d42ebfe04f890c83c7006", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Not found" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/cost-centers": { "get": { "tags": [ "Cost Centers" ], "summary": "List cost centers", "description": "Returns a paginated list of cost centers with optional filtering.", "operationId": "63c45d896714a398cfb730777d5946ca", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "is_active", "in": "query", "description": "Filter by active status", "required": false, "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "code" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "asc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of cost centers", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CostCenter" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Cost Centers" ], "summary": "Create cost center", "description": "Creates a new cost center record.", "operationId": "67ba25182eeec034913a3463eed83449", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "code", "name" ], "properties": { "code": { "type": "string", "example": "CC-001", "maxLength": 50 }, "name": { "type": "string", "example": "Operations", "maxLength": 255 }, "type": { "type": "string", "nullable": true, "maxLength": 50 }, "parent_id": { "type": "integer", "nullable": true }, "is_active": { "type": "boolean", "example": true }, "description": { "type": "string", "nullable": true, "maxLength": 1000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Cost center created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/CostCenter" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/cost-centers/{id}": { "get": { "tags": [ "Cost Centers" ], "summary": "Get cost center by ID", "description": "Returns a single cost center record.", "operationId": "57ea87d3bd98dd0ba198447a6b65fddf", "parameters": [ { "name": "id", "in": "path", "description": "Cost Center ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Cost center details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/CostCenter" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Cost Centers" ], "summary": "Update cost center", "description": "Updates an existing cost center record.", "operationId": "ea5304caea384e2010903befd7ed8b6c", "parameters": [ { "name": "id", "in": "path", "description": "Cost Center ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "code", "name" ], "properties": { "code": { "type": "string", "maxLength": 50 }, "name": { "type": "string", "maxLength": 255 }, "type": { "type": "string", "nullable": true, "maxLength": 50 }, "parent_id": { "type": "integer", "nullable": true }, "is_active": { "type": "boolean" }, "description": { "type": "string", "nullable": true, "maxLength": 1000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Cost center updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/CostCenter" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Cost Centers" ], "summary": "Delete cost center", "description": "Soft-deletes a cost center record.", "operationId": "b5f65eb941f26d5e235b88c59dce95a0", "parameters": [ { "name": "id", "in": "path", "description": "Cost Center ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Cost center deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/currencies": { "get": { "tags": [ "Currencies" ], "summary": "List currencies", "description": "Returns a paginated list of currencies with optional filtering.", "operationId": "cc96e72a6ab0802a84471e6bd12939f3", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "is_active", "in": "query", "description": "Filter by active status", "required": false, "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "code" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "asc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of currencies", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Currency" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Currencies" ], "summary": "Create currency", "description": "Creates a new currency record.", "operationId": "006da176a619dd605a24bd778b9a8a91", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "code", "name", "symbol", "exchange_rate" ], "properties": { "code": { "type": "string", "example": "USD", "maxLength": 10 }, "name": { "type": "string", "example": "US Dollar", "maxLength": 100 }, "symbol": { "type": "string", "example": "$", "maxLength": 10 }, "exchange_rate": { "type": "number", "format": "float", "example": 1 }, "is_base": { "type": "boolean", "example": false }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Currency created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/Currency" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/currencies/{id}": { "get": { "tags": [ "Currencies" ], "summary": "Get currency by ID", "description": "Returns a single currency record.", "operationId": "fa5d6cbd4c60c452731eeafe4cf2daad", "parameters": [ { "name": "id", "in": "path", "description": "Currency ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Currency details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Currency" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Currencies" ], "summary": "Update currency", "description": "Updates an existing currency record.", "operationId": "6189701ad5782fcf7854c2d490828933", "parameters": [ { "name": "id", "in": "path", "description": "Currency ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "code", "name", "symbol", "exchange_rate" ], "properties": { "code": { "type": "string", "maxLength": 10 }, "name": { "type": "string", "maxLength": 100 }, "symbol": { "type": "string", "maxLength": 10 }, "exchange_rate": { "type": "number", "format": "float" }, "is_base": { "type": "boolean" }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Currency updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Currency" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Currencies" ], "summary": "Delete currency", "description": "Deletes a currency record.", "operationId": "2ecae329aaedcc0642529d9c45481699", "parameters": [ { "name": "id", "in": "path", "description": "Currency ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Currency deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/currencies/{id}/set-base": { "post": { "tags": [ "Currencies" ], "summary": "Set base currency", "description": "Designates this currency as the base currency (exchange_rate set to 1.0). Clears the base flag from all other currencies in the same company.", "operationId": "4ad4ef789cdcc917b44a02aa97292c30", "parameters": [ { "name": "id", "in": "path", "description": "Currency ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Base currency updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Currency" } }, "type": "object" } } } }, "422": { "description": "Currency is already the base currency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/currency-revaluation": { "get": { "tags": [ "Currency Revaluation" ], "summary": "List past currency revaluation entries", "description": "Returns a paginated list of posted FX revaluation journal entries.", "operationId": "8f73f75905f2e1c6d6f705af4bd94c6f", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100 } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "default": "entry_date" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of revaluation journal entries", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Currency Revaluation" ], "summary": "Run currency revaluation", "description": "Revalues all foreign-currency monetary accounts at the given date (IFRS 21). Use dry_run=true to preview without posting.", "operationId": "9bf22665803ef80edb6f51985eefebe6", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "as_of_date" ], "properties": { "as_of_date": { "description": "Revaluation date (typically period-end)", "type": "string", "format": "date", "example": "2025-03-31" }, "dry_run": { "description": "If true, return preview without posting", "type": "boolean", "example": false } }, "type": "object" } } } }, "responses": { "200": { "description": "Revaluation result", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "properties": { "dry_run": { "type": "boolean" }, "as_of_date": { "type": "string", "format": "date" }, "total_gain_loss": { "type": "number", "format": "float" }, "journal_entry_id": { "type": "integer", "nullable": true }, "entries": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation or configuration error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/customers": { "get": { "tags": [ "Customers" ], "summary": "List customers", "description": "Returns a paginated list of customers with optional search and sorting.", "operationId": "2a2e8777a73f84307e0af1db6bbd9b03", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Search by name, email, or phone", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at", "enum": [ "name", "email", "created_at" ] } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of customers", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Customers" ], "summary": "Create customer", "description": "Creates a new customer record.", "operationId": "047828a976c6178185a7716d2bad1117", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Acme Corp", "maxLength": 255 }, "email": { "type": "string", "format": "email", "example": "info@acme.com", "nullable": true }, "phone": { "type": "string", "example": "+966500000000", "nullable": true, "maxLength": 50 }, "tax_number": { "type": "string", "example": "300000000000003", "nullable": true, "maxLength": 50 }, "billing_address": { "type": "string", "nullable": true, "maxLength": 500 }, "shipping_address": { "type": "string", "nullable": true, "maxLength": 500 }, "city": { "type": "string", "example": "Riyadh", "nullable": true, "maxLength": 100 }, "country": { "type": "string", "example": "SA", "nullable": true, "maxLength": 100 }, "currency_id": { "type": "integer", "example": 1, "nullable": true }, "credit_limit": { "type": "number", "format": "float", "example": 10000, "nullable": true }, "payment_terms_days": { "type": "integer", "example": 30, "nullable": true }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Customer created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/Customer" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/customers/{id}": { "get": { "tags": [ "Customers" ], "summary": "Get customer by ID", "description": "Returns a single customer record.", "operationId": "cb7e8ad8143b86ef091b8c1ef7e43112", "parameters": [ { "name": "id", "in": "path", "description": "Customer ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Customer details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Customer" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Customers" ], "summary": "Update customer", "description": "Updates an existing customer record.", "operationId": "018c3bd45ded494567ee8d0bfa6d6a0f", "parameters": [ { "name": "id", "in": "path", "description": "Customer ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Acme Corp", "maxLength": 255 }, "email": { "type": "string", "format": "email", "example": "info@acme.com", "nullable": true }, "phone": { "type": "string", "example": "+966500000000", "nullable": true, "maxLength": 50 }, "tax_number": { "type": "string", "nullable": true, "maxLength": 50 }, "billing_address": { "type": "string", "nullable": true, "maxLength": 500 }, "shipping_address": { "type": "string", "nullable": true, "maxLength": 500 }, "city": { "type": "string", "nullable": true, "maxLength": 100 }, "country": { "type": "string", "nullable": true, "maxLength": 100 }, "currency_id": { "type": "integer", "nullable": true }, "credit_limit": { "type": "number", "format": "float", "nullable": true }, "payment_terms_days": { "type": "integer", "nullable": true }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Customer updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Customer" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Customers" ], "summary": "Delete customer", "description": "Soft-deletes a customer record.", "operationId": "2eed1acfdaef0017ce5a7ddea999b1d6", "parameters": [ { "name": "id", "in": "path", "description": "Customer ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Customer deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/departments": { "get": { "tags": [ "Departments" ], "summary": "List departments", "description": "Returns a paginated list of departments with optional name search.", "operationId": "87358e000f92693bdc7b2c9846c82795", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Search by name", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of departments", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Department" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Departments" ], "summary": "Create department", "description": "Creates a new department.", "operationId": "d4635ae7b4c15efca40765102f9ff8d6", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Engineering", "maxLength": 255 }, "code": { "type": "string", "example": "ENG", "nullable": true, "maxLength": 50 }, "parent_id": { "type": "integer", "example": null, "nullable": true }, "manager_id": { "type": "integer", "example": 1, "nullable": true }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Department created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/Department" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/departments/{id}": { "get": { "tags": [ "Departments" ], "summary": "Get department by ID", "description": "Returns a single department record.", "operationId": "01c2d12e14cd820aa51b5ccdc59c29eb", "parameters": [ { "name": "id", "in": "path", "description": "Department ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Department details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Department" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Departments" ], "summary": "Update department", "description": "Updates an existing department.", "operationId": "cbc0a492f9379edab60b247e7d04a7ae", "parameters": [ { "name": "id", "in": "path", "description": "Department ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "code": { "type": "string", "nullable": true, "maxLength": 50 }, "parent_id": { "type": "integer", "nullable": true }, "manager_id": { "type": "integer", "nullable": true }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Department updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Department" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Departments" ], "summary": "Delete department", "description": "Deletes a department record.", "operationId": "068f2ed74585edcde1c2f968caa9e9b2", "parameters": [ { "name": "id", "in": "path", "description": "Department ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Department deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/ess/approvals/pending": { "get": { "tags": [ "ESS Approvals" ], "summary": "My pending approvals", "description": "Returns all workflow approval tasks currently awaiting a decision from the authenticated user (manager / HR role). Use `approve`, `reject`, or `delegate` to act on each item.", "operationId": "a59e7950d4463f2c24f9949eb689279b", "responses": { "200": { "description": "Array of pending approval tasks", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "approval_id": { "type": "integer" }, "instance_id": { "type": "integer" }, "entity_type": { "type": "string", "example": "leave_request" }, "subject": { "type": "string" }, "step_order": { "type": "integer" }, "decision": { "type": "string", "enum": [ "pending", "approved", "rejected" ] }, "workflow_status": { "type": "string" }, "submitted_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "EssBearerAuth": [] } ] } }, "/ess/approvals/{instanceId}/approve": { "post": { "tags": [ "ESS Approvals" ], "summary": "Approve a workflow step", "operationId": "050a4334ef055b2c0089ee0463e8623d", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "comments": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Approved — new workflow status returned" }, "403": { "description": "Not an approver for this step" } }, "security": [ { "EssBearerAuth": [] } ] } }, "/ess/approvals/{instanceId}/reject": { "post": { "tags": [ "ESS Approvals" ], "summary": "Reject a workflow step", "operationId": "9bb1a0740cc4da539de07fbd5557859f", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "comments" ], "properties": { "comments": { "type": "string", "example": "Insufficient leave balance." } }, "type": "object" } } } }, "responses": { "200": { "description": "Rejected" }, "403": { "description": "Not an approver for this step" }, "422": { "description": "comments field is required" } }, "security": [ { "EssBearerAuth": [] } ] } }, "/ess/approvals/{instanceId}/delegate": { "post": { "tags": [ "ESS Approvals" ], "summary": "Delegate an approval to another user", "operationId": "f306f985f22689f8dbbed0fcbeb2b521", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "delegate_user_id" ], "properties": { "delegate_user_id": { "type": "integer", "example": 7 } }, "type": "object" } } } }, "responses": { "200": { "description": "Delegated successfully" }, "403": { "description": "Not an approver for this step" } }, "security": [ { "EssBearerAuth": [] } ] } }, "/ess/approvals/history": { "get": { "tags": [ "ESS Approvals" ], "summary": "My approval history", "description": "Returns approvals the authenticated user has already acted on in the last 90 days.", "operationId": "ba132a8e317a758154aafc9c876ee8ae", "parameters": [ { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Paginated approval history" }, "401": { "description": "Unauthenticated" } }, "security": [ { "EssBearerAuth": [] } ] } }, "/ess/auth/login": { "post": { "tags": [ "ESS Auth" ], "summary": "ESS Login", "description": "Authenticate an employee with email and password. Returns a bearer token (valid 90 days) to be sent with all subsequent ESS requests via `Authorization: Bearer `.", "operationId": "4b9b64e597808669b8e92c99256f8da1", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "ahmed@company.sa" }, "password": { "type": "string", "format": "password" }, "device_name": { "type": "string", "example": "iPhone 15", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Login successful — returns token and employee info", "content": { "application/json": { "schema": { "properties": { "token": { "type": "string", "example": "ess_abc123..." }, "expires_at": { "type": "string", "format": "date-time" }, "employee": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "position": { "type": "string", "nullable": true }, "department": { "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Invalid credentials" }, "403": { "description": "No employee account linked or account terminated" } } } }, "/ess/auth/logout": { "delete": { "tags": [ "ESS Auth" ], "summary": "ESS Logout", "description": "Revoke the current ESS bearer token.", "operationId": "45d717fd7bf2a7259fb5a029ef1863e8", "responses": { "200": { "description": "Logged out" }, "401": { "description": "Invalid or expired token" } }, "security": [ { "EssBearerAuth": [] } ] } }, "/ess/auth/refresh": { "post": { "tags": [ "ESS Auth" ], "summary": "Refresh ESS token", "description": "Extend the current token expiry by 90 days.", "operationId": "be80f024f1b01fe5b195571399de57f7", "responses": { "200": { "description": "New expiry returned", "content": { "application/json": { "schema": { "properties": { "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "401": { "description": "Invalid or expired token" } }, "security": [ { "EssBearerAuth": [] } ] } }, "/ess/hr-letters": { "get": { "tags": [ "ESS HR Letters" ], "summary": "List my HR letter requests", "operationId": "7db38cfe35f5a57ee3fa84cb602112c1", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "processing", "ready", "delivered", "cancelled" ] } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Paginated HR letter requests" }, "401": { "description": "Unauthenticated" } }, "security": [ { "EssBearerAuth": [] } ] }, "post": { "tags": [ "ESS HR Letters" ], "summary": "Request an HR letter", "description": "Creates an HR letter request (e.g. salary certificate, employment letter) in `pending` status. If a workflow template is configured it is triggered automatically.", "operationId": "56b134df0828f84ad82d820c97cb7aa3", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "letter_type", "language" ], "properties": { "letter_type": { "type": "string", "enum": [ "salary_certificate", "employment_certificate", "experience_letter", "noc", "bank_letter" ] }, "language": { "type": "string", "enum": [ "ar", "en" ] }, "addressed_to": { "type": "string", "example": "Saudi National Bank", "nullable": true }, "purpose": { "type": "string", "nullable": true }, "copies_needed": { "type": "integer", "nullable": true, "default": 1 }, "notes": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "HR letter request created" }, "422": { "description": "Validation error" } }, "security": [ { "EssBearerAuth": [] } ] } }, "/ess/hr-letters/{id}": { "get": { "tags": [ "ESS HR Letters" ], "summary": "Get a single HR letter request", "operationId": "28f780ae9fb8f52603466703c15b21cc", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "HR letter detail" }, "404": { "description": "Not found" } }, "security": [ { "EssBearerAuth": [] } ] } }, "/ess/leave-types": { "get": { "tags": [ "ESS Leaves" ], "summary": "List available leave types", "operationId": "9a5a31fc7f2368994e9cd5ed4ffddaac", "responses": { "200": { "description": "Leave types array" }, "401": { "description": "Unauthenticated" } }, "security": [ { "EssBearerAuth": [] } ] } }, "/ess/leaves": { "get": { "tags": [ "ESS Leaves" ], "summary": "List my leave requests", "operationId": "991916e73a17aad7509ced27bf780436", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "submitted", "approved", "rejected", "cancelled" ] } }, { "name": "year", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Paginated leave requests" }, "401": { "description": "Unauthenticated" } }, "security": [ { "EssBearerAuth": [] } ] }, "post": { "tags": [ "ESS Leaves" ], "summary": "Submit a leave request", "description": "Creates a leave request in `submitted` status. If a matching approval workflow template is configured, the workflow is triggered automatically.", "operationId": "795d87145655d8eace2cc15f8a6de8cc", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "leave_type_id", "start_date", "end_date" ], "properties": { "leave_type_id": { "type": "integer", "example": 1 }, "start_date": { "type": "string", "format": "date", "example": "2026-07-01" }, "end_date": { "type": "string", "format": "date", "example": "2026-07-05" }, "reason": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Leave request created" }, "422": { "description": "Validation error" } }, "security": [ { "EssBearerAuth": [] } ] } }, "/ess/leaves/{id}": { "get": { "tags": [ "ESS Leaves" ], "summary": "Get a single leave request", "operationId": "7d37fa52b5bfb43a5e71573da0bfa2c4", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Leave request detail" }, "404": { "description": "Not found" } }, "security": [ { "EssBearerAuth": [] } ] }, "delete": { "tags": [ "ESS Leaves" ], "summary": "Cancel a leave request", "description": "Only requests in `draft` or `submitted` status can be cancelled. The active workflow instance is also cancelled.", "operationId": "7b1ee840ae16de4cf46806364bccfb85", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Cancelled" }, "422": { "description": "Request cannot be cancelled in its current status" } }, "security": [ { "EssBearerAuth": [] } ] } }, "/ess/loans": { "get": { "tags": [ "ESS Loans" ], "summary": "List my loan/advance requests", "operationId": "96c2f4e8afd84cb58039c783ff84a03c", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "active", "settled" ] } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "loan", "advance" ] } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Paginated loan requests" }, "401": { "description": "Unauthenticated" } }, "security": [ { "EssBearerAuth": [] } ] }, "post": { "tags": [ "ESS Loans" ], "summary": "Submit a loan or salary advance request", "description": "Creates a loan request in `pending` status. If a matching approval workflow is configured, it is triggered automatically.", "operationId": "2ad23e05944323b242454ce21e0c8c6f", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "type", "requested_amount", "repayment_months" ], "properties": { "type": { "type": "string", "enum": [ "loan", "advance" ] }, "requested_amount": { "type": "number", "example": 5000 }, "repayment_months": { "type": "integer", "example": 6 }, "reason": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Loan request created" }, "422": { "description": "Validation error" } }, "security": [ { "EssBearerAuth": [] } ] } }, "/ess/loans/{id}": { "get": { "tags": [ "ESS Loans" ], "summary": "Get a single loan request", "operationId": "725d4b4854d4452a63410fafff72d5b8", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Loan detail" }, "404": { "description": "Not found" } }, "security": [ { "EssBearerAuth": [] } ] } }, "/ess/payslips": { "get": { "tags": [ "ESS Payslips" ], "summary": "List my payslips", "description": "Returns paginated payslips for the authenticated employee. Only paid payrolls are returned.", "operationId": "927d5d48f591290b5bafcc4477625720", "parameters": [ { "name": "year", "in": "query", "required": false, "schema": { "type": "integer", "example": 2026 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 12 } } ], "responses": { "200": { "description": "Paginated payslip list", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "reference": { "type": "string" }, "month": { "type": "integer" }, "year": { "type": "integer" }, "pay_date": { "type": "string", "format": "date" }, "basic_salary": { "type": "number" }, "total_earnings": { "type": "number" }, "total_deductions": { "type": "number" }, "net_pay": { "type": "number" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "EssBearerAuth": [] } ] } }, "/ess/payslips/{id}": { "get": { "tags": [ "ESS Payslips" ], "summary": "Get a single payslip", "description": "Returns the full payslip including individual earnings and deduction components.", "operationId": "3a6998ea9b274840402fe62f189fe239", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payslip detail with components array" }, "403": { "description": "Payslip does not belong to this employee" }, "404": { "description": "Not found" } }, "security": [ { "EssBearerAuth": [] } ] } }, "/ess/profile": { "get": { "tags": [ "ESS Profile" ], "summary": "Get my profile", "description": "Returns the full profile of the authenticated employee including personal details, document expiry dates, and salary components.", "operationId": "28805d2c5eb71d6de2eff95f1318e32d", "responses": { "200": { "description": "Employee profile", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer" }, "employee_number": { "type": "string" }, "full_name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "position": { "type": "string", "nullable": true }, "department": { "type": "string", "nullable": true }, "hire_date": { "type": "string", "format": "date" }, "iqama_expiry_date": { "type": "string", "format": "date", "nullable": true }, "iqama_status": { "type": "string", "enum": [ "valid", "expiring", "expiring_soon", "expired", "not_applicable" ] }, "basic_salary": { "type": "number", "format": "float" } }, "type": "object" } } } }, "401": { "description": "Invalid or expired ESS token" } }, "security": [ { "EssBearerAuth": [] } ] }, "put": { "tags": [ "ESS Profile" ], "summary": "Update my profile", "description": "Employees may update their own phone and marital status only. All other fields are managed by HR.", "operationId": "d7fbd220474aaf5d4fcd64311001bb68", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "phone": { "type": "string", "example": "+966501234567", "nullable": true }, "marital_status": { "type": "string", "nullable": true, "enum": [ "single", "married", "divorced", "widowed" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile updated" }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error" } }, "security": [ { "EssBearerAuth": [] } ] } }, "/ess/profile/leave-balances": { "get": { "tags": [ "ESS Profile" ], "summary": "Get my leave balances", "description": "Returns leave balance for each leave type for the specified year (defaults to current year).", "operationId": "f7ab2e5d5899817b43ef2ee05e1e138e", "parameters": [ { "name": "year", "in": "query", "required": false, "schema": { "type": "integer", "example": 2026 } } ], "responses": { "200": { "description": "Leave balances array", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "leave_type": { "type": "string" }, "year": { "type": "integer" }, "days_allocated": { "type": "number" }, "days_used": { "type": "number" }, "days_remaining": { "type": "number" } }, "type": "object" } } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "EssBearerAuth": [] } ] } }, "/employee-cars": { "get": { "tags": [ "Employee Cars" ], "summary": "List employee cars", "description": "Returns a paginated list of company vehicles. Filter by status, expiring documents, or assigned employee.", "operationId": "f3f0e2f1b61e3ded6164abe6acd08be1", "parameters": [ { "name": "employee_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "assigned", "available", "maintenance", "retired" ] } }, { "name": "expiring", "in": "query", "description": "Return cars with documents expiring within `days` days", "required": false, "schema": { "type": "boolean" } }, { "name": "days", "in": "query", "description": "Look-ahead window when expiring=true (default 90)", "required": false, "schema": { "type": "integer", "default": 90 } }, { "name": "expired", "in": "query", "description": "Return cars with at least one expired document", "required": false, "schema": { "type": "boolean" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Paginated list of vehicles" }, "401": { "description": "Unauthenticated" } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Employee Cars" ], "summary": "Create a vehicle record", "operationId": "34ef1702e41f057cca69a7d8d75af4d6", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "plate_number" ], "properties": { "employee_id": { "type": "integer", "example": 5, "nullable": true }, "plate_number": { "type": "string", "example": "ABC 1234" }, "make": { "type": "string", "example": "Toyota" }, "model": { "type": "string", "example": "Camry" }, "year": { "type": "integer", "example": 2023 }, "color": { "type": "string", "example": "White" }, "chassis_number": { "type": "string", "nullable": true }, "vehicle_license_expiry_date": { "type": "string", "format": "date", "example": "2025-12-31" }, "insurance_expiry_date": { "type": "string", "format": "date", "nullable": true }, "driver_license_expiry_date": { "type": "string", "format": "date", "nullable": true }, "insurance_company": { "type": "string", "nullable": true }, "insurance_policy_number": { "type": "string", "nullable": true }, "assigned_date": { "type": "string", "format": "date", "nullable": true }, "status": { "type": "string", "default": "assigned", "enum": [ "assigned", "available", "maintenance", "retired" ] }, "notes": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Vehicle created" }, "422": { "description": "Validation error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/employee-cars/expiry-summary": { "get": { "tags": [ "Employee Cars" ], "summary": "Document expiry summary", "description": "Returns counts of expired and expiring-soon documents grouped by type (vehicle license, insurance, driver license).", "operationId": "490f1b7731f64deda88b5805c61d73b0", "responses": { "200": { "description": "Expiry counts per document type", "content": { "application/json": { "schema": { "properties": { "vehicle_license": { "properties": { "expired": { "type": "integer" }, "expiring_30": { "type": "integer" }, "expiring_90": { "type": "integer" } }, "type": "object" }, "insurance": { "type": "object" }, "driver_license": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/employee-cars/{id}": { "get": { "tags": [ "Employee Cars" ], "summary": "Get a single vehicle", "operationId": "375da4360088c558213a73782fbe4351", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Vehicle detail" }, "404": { "description": "Not found" } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Employee Cars" ], "summary": "Update a vehicle record", "operationId": "2188f510f765576548b246b24ffee259", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Vehicle updated" }, "404": { "description": "Not found" }, "422": { "description": "Validation error" } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Employee Cars" ], "summary": "Soft-delete a vehicle", "operationId": "270c8c93c15cff62712232cfa7fc3e5c", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted" }, "404": { "description": "Not found" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/employees": { "get": { "tags": [ "Employees" ], "summary": "List employees", "description": "Returns a paginated list of employees with optional search and filtering.", "operationId": "69d4913dbe48d86c7616c4b511a07b3f", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Search by name or email", "required": false, "schema": { "type": "string" } }, { "name": "department_id", "in": "query", "description": "Filter by department ID", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive", "terminated" ] } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of employees", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Employee" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Employees" ], "summary": "Create employee", "description": "Creates a new employee record.", "operationId": "38d8e9dc232fc6fdf22aac5c97cd7570", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "first_name", "last_name" ], "properties": { "first_name": { "type": "string", "example": "Ahmed", "maxLength": 255 }, "last_name": { "type": "string", "example": "Al-Rashid", "maxLength": 255 }, "email": { "type": "string", "format": "email", "example": "ahmed@company.com", "nullable": true }, "phone": { "type": "string", "example": "+966500000002", "nullable": true, "maxLength": 50 }, "department_id": { "type": "integer", "example": 1, "nullable": true }, "manager_id": { "type": "integer", "nullable": true }, "position": { "type": "string", "example": "Accountant", "nullable": true, "maxLength": 255 }, "employment_type": { "type": "string", "example": "full_time", "nullable": true, "maxLength": 50 }, "hire_date": { "type": "string", "format": "date", "example": "2022-06-01", "nullable": true }, "basic_salary": { "type": "number", "format": "float", "example": 8000, "nullable": true }, "status": { "type": "string", "example": "active", "nullable": true, "maxLength": 50 }, "national_id": { "type": "string", "nullable": true, "maxLength": 50 } }, "type": "object" } } } }, "responses": { "201": { "description": "Employee created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/Employee" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/employees/{id}": { "get": { "tags": [ "Employees" ], "summary": "Get employee by ID", "description": "Returns a single employee record.", "operationId": "f2861450172cd25374ad5e58bfd0f8ae", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Employee details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Employee" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Employees" ], "summary": "Update employee", "description": "Updates an existing employee record.", "operationId": "2a2f9b0f5dd91db6a5948d081d5db4eb", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "first_name", "last_name" ], "properties": { "first_name": { "type": "string", "example": "Ahmed", "maxLength": 255 }, "last_name": { "type": "string", "example": "Al-Rashid", "maxLength": 255 }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "type": "string", "nullable": true, "maxLength": 50 }, "department_id": { "type": "integer", "nullable": true }, "manager_id": { "type": "integer", "nullable": true }, "position": { "type": "string", "nullable": true, "maxLength": 255 }, "employment_type": { "type": "string", "nullable": true, "maxLength": 50 }, "hire_date": { "type": "string", "format": "date", "nullable": true }, "basic_salary": { "type": "number", "format": "float", "nullable": true }, "status": { "type": "string", "nullable": true, "maxLength": 50 }, "national_id": { "type": "string", "nullable": true, "maxLength": 50 } }, "type": "object" } } } }, "responses": { "200": { "description": "Employee updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Employee" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/employees/{id}/terminate": { "post": { "tags": [ "Employees" ], "summary": "Terminate employee", "description": "Sets the employee status to terminated.", "operationId": "582bbdafe79ff04ab5b527afba7682cf", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "termination_date": { "description": "Defaults to today if not provided", "type": "string", "format": "date", "example": "2024-03-31", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Employee terminated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Employee" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/employees/{id}/compensation": { "put": { "tags": [ "Employees" ], "summary": "Update employee compensation", "description": "Updates salary and allowances. Requires elevated compensation.update permission (separate from general employee editing).", "operationId": "c04dfe12932735563d169faeef3269d5", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "basic_salary" ], "properties": { "basic_salary": { "type": "number", "format": "float", "example": 10000, "minimum": 0 }, "housing_allowance": { "type": "number", "format": "float", "example": 2000, "nullable": true, "minimum": 0 }, "transport_allowance": { "type": "number", "format": "float", "example": 800, "nullable": true, "minimum": 0 } }, "type": "object" } } } }, "responses": { "200": { "description": "Compensation updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Employee" } }, "type": "object" } } } }, "403": { "description": "Insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/employees/{id}/bank-account": { "put": { "tags": [ "Employees" ], "summary": "Update employee bank account", "description": "Updates IBAN and bank account. Every change is immutably logged with masked old/new values, IP address, and timestamp. Duplicate IBAN within the company is rejected.", "operationId": "93b9ba56a18da7511ea18012e7ff4b64", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "iban" ], "properties": { "iban": { "type": "string", "example": "SA0380000000608010167519", "maxLength": 34 }, "bank_account": { "type": "string", "example": "608010167519", "nullable": true, "maxLength": 50 } }, "type": "object" } } } }, "responses": { "200": { "description": "Bank account updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Employee" } }, "type": "object" } } } }, "422": { "description": "Duplicate IBAN or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/employees/{id}/reactivate": { "post": { "tags": [ "Employees" ], "summary": "Reactivate employee", "description": "Sets a terminated or inactive employee back to active status.", "operationId": "f78900bb57fe1f4994464cbb598a0cfb", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Employee reactivated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Employee" } }, "type": "object" } } } }, "422": { "description": "Employee is not terminated or inactive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/employees/{id}/leave-balances": { "get": { "tags": [ "Employees" ], "summary": "Get employee leave balances", "description": "Returns the leave balances for the given employee grouped by leave type and year.", "operationId": "3e54346d6323db39ae99421d705402a9", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Leave balances", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "leave_type_id": { "type": "integer", "example": 2 }, "leave_type_name": { "type": "string", "example": "Annual Leave", "nullable": true }, "year": { "type": "integer", "example": 2024 }, "allocated": { "type": "number", "format": "float", "example": 21 }, "used": { "type": "number", "format": "float", "example": 5 }, "remaining": { "type": "number", "format": "float", "example": 16 } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/eos": { "get": { "tags": [ "End of Service" ], "summary": "List End-of-Service records", "description": "Returns a paginated list of terminated employees with EOS settlement details.", "operationId": "263dbf7cc83ba4d5c6876625321adbca", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "employee_id", "in": "query", "description": "Filter by employee ID", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "description": "Filter by employee status", "required": false, "schema": { "type": "string", "enum": [ "terminated" ] } } ], "responses": { "200": { "description": "Paginated list of EOS records", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Eos" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "End of Service" ], "summary": "Settle End-of-Service", "description": "Calculates and saves the EOS gratuity, marks the employee as terminated, and stores all EOS fields on the employee record.", "operationId": "43cf014749f16308b8fbe946220de17c", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "employee_id", "termination_date", "termination_reason" ], "properties": { "employee_id": { "type": "integer", "example": 1 }, "termination_date": { "type": "string", "format": "date", "example": "2026-05-31" }, "termination_reason": { "type": "string", "example": "termination", "enum": [ "resignation", "termination", "retirement", "death", "mutual_agreement", "redundancy", "termination_with_cause" ] }, "exgratia_days": { "description": "Discretionary ex-gratia days", "type": "number", "format": "float", "example": 0, "nullable": true }, "encash_leave_balance": { "description": "Whether to include leave encashment", "type": "boolean", "example": true, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "EOS settlement completed, employee terminated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/Eos" } }, "type": "object" } } } }, "422": { "description": "Validation or business rule error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Employee not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/eos/{id}": { "get": { "tags": [ "End of Service" ], "summary": "Get EOS record by employee ID", "description": "Returns EOS settlement details for a specific employee.", "operationId": "f8d9311672add135f976dfd54dec586a", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "EOS record details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Eos" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/eos/calculate": { "post": { "tags": [ "End of Service" ], "summary": "Calculate EOS (dry run)", "description": "Calculates End-of-Service gratuity per Saudi Labor Law Article 84 WITHOUT saving. Returns full calculation breakdown.", "operationId": "f8dc4864c25ffa95491c65ddfcfd2dcd", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "employee_id", "termination_date", "termination_reason" ], "properties": { "employee_id": { "type": "integer", "example": 1 }, "termination_date": { "type": "string", "format": "date", "example": "2026-05-31" }, "termination_reason": { "type": "string", "example": "termination", "enum": [ "resignation", "termination", "retirement", "death", "mutual_agreement", "redundancy", "termination_with_cause" ] }, "exgratia_days": { "description": "Discretionary ex-gratia days on top of statutory EOSB", "type": "number", "format": "float", "example": 0, "nullable": true }, "encash_leave_balance": { "description": "Whether to include leave encashment in calculation", "type": "boolean", "example": true, "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "EOS calculation result (not saved)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "properties": { "hire_date": { "type": "string", "format": "date" }, "termination_date": { "type": "string", "format": "date" }, "termination_reason": { "type": "string" }, "total_years": { "type": "number", "format": "float" }, "whole_years": { "type": "integer" }, "partial_year": { "type": "number", "format": "float" }, "basic_salary": { "type": "number", "format": "float" }, "housing_allowance": { "type": "number", "format": "float" }, "base_wage": { "type": "number", "format": "float" }, "daily_rate": { "type": "number", "format": "float" }, "eosb_amount": { "type": "number", "format": "float" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error or calculation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Employee not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/expense-categories": { "get": { "tags": [ "Expense Categories" ], "summary": "List expense categories", "description": "Returns a paginated list of expense categories with optional search.", "operationId": "df9a1634c50d128e5c9968eac869a998", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100 } }, { "name": "search", "in": "query", "description": "Search by name", "required": false, "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "description": "Filter by active status", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "default": "name" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "default": "asc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of expense categories", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Expense Categories" ], "summary": "Create expense category", "description": "Creates a new expense category.", "operationId": "2090bfa86c3bde811b7832c4f7b03fa6", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Travel", "maxLength": 255 }, "description": { "type": "string", "nullable": true }, "expense_account_id": { "description": "GL account ID", "type": "integer", "nullable": true }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Expense category created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/expense-categories/{id}": { "get": { "tags": [ "Expense Categories" ], "summary": "Get expense category by ID", "description": "Returns a single expense category with expenses count.", "operationId": "df7067dcf1e8accfe8341fcde69f1f19", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Expense category details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Expense Categories" ], "summary": "Update expense category", "description": "Updates an existing expense category.", "operationId": "2a974a77d4d3de03a1035968ba071ac7", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "nullable": true }, "expense_account_id": { "type": "integer", "nullable": true }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Expense category updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Expense Categories" ], "summary": "Delete expense category", "description": "Soft-deletes an expense category. Fails if expenses are linked.", "operationId": "1f52aa68b1a7afe4c5316991e0a44eca", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Expense category deleted" }, "422": { "description": "Expenses are linked to this category", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/expenses": { "get": { "tags": [ "Expenses" ], "summary": "List expenses", "description": "Returns a paginated list of expenses with optional filtering.", "operationId": "02dd0399645db746ef68a9bcdab69338", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100 } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "draft", "submitted", "approved", "rejected", "paid" ] } }, { "name": "employee_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "date_from", "in": "query", "description": "Filter from date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Filter to date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "default": "expense_date" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of expenses", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Expenses" ], "summary": "Create expense", "description": "Creates a new expense in draft status.", "operationId": "c751fc8afec0e421ff4180beb6d02e87", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "expense_date" ], "properties": { "expense_date": { "type": "string", "format": "date", "example": "2025-03-15" }, "employee_id": { "type": "integer", "nullable": true }, "branch_id": { "type": "integer", "nullable": true }, "currency_id": { "type": "integer", "nullable": true }, "exchange_rate": { "type": "number", "format": "float", "nullable": true }, "payment_account_id": { "type": "integer", "nullable": true }, "notes": { "type": "string", "nullable": true }, "reference": { "type": "string", "nullable": true }, "lines": { "type": "array", "items": { "required": [ "description", "amount" ], "properties": { "description": { "type": "string" }, "amount": { "type": "number", "format": "float" }, "account_id": { "type": "integer", "nullable": true }, "tax_rate": { "type": "number", "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Expense created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/expenses/{id}": { "get": { "tags": [ "Expenses" ], "summary": "Get expense by ID", "description": "Returns a single expense with lines and payment info.", "operationId": "816cba9dcf02e041a8b7a8070d498a6d", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Expense details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Expenses" ], "summary": "Update expense", "description": "Updates a draft expense.", "operationId": "eb395073943129ebe9c47ddb07209b54", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "expense_date": { "type": "string", "format": "date" }, "notes": { "type": "string", "nullable": true }, "reference": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Expense updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Only draft expenses can be updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Expenses" ], "summary": "Delete expense", "description": "Soft-deletes a draft expense.", "operationId": "c26749846eda472abe88d46c3823f030", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Expense deleted" }, "422": { "description": "Only draft expenses can be deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/expenses/{id}/approve": { "post": { "tags": [ "Expenses" ], "summary": "Approve expense", "description": "Sets expense status to approved.", "operationId": "3a2cc7b9a2327cf27a631651d334d6c9", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Expense approved", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Expense must be in submitted or draft status to approve", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/expenses/{id}/reject": { "post": { "tags": [ "Expenses" ], "summary": "Reject expense", "description": "Sets expense status to rejected and records the reason.", "operationId": "407926a3172f92e439b360ec400bfc4c", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reason" ], "properties": { "reason": { "type": "string", "example": "Missing receipts" } }, "type": "object" } } } }, "responses": { "200": { "description": "Expense rejected", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Expense cannot be rejected in current status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/fiscal-years": { "get": { "tags": [ "Fiscal Years" ], "summary": "List fiscal years", "description": "Returns a paginated list of fiscal years with optional filtering.", "operationId": "624477778f87031b13bd4610ee85a602", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "open", "closed", "locked" ] } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "start_date" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of fiscal years", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/FiscalYear" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Fiscal Years" ], "summary": "Create fiscal year", "description": "Creates a new fiscal year. Status is set to open.", "operationId": "4fadeb1dd2993202f27f15edad02763b", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "start_date", "end_date" ], "properties": { "name": { "type": "string", "example": "FY 2025", "maxLength": 255 }, "start_date": { "type": "string", "format": "date", "example": "2025-01-01" }, "end_date": { "type": "string", "format": "date", "example": "2025-12-31" } }, "type": "object" } } } }, "responses": { "201": { "description": "Fiscal year created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/FiscalYear" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/fiscal-years/{id}": { "get": { "tags": [ "Fiscal Years" ], "summary": "Get fiscal year by ID", "description": "Returns a single fiscal year record.", "operationId": "d7c4b9281c5fc86eeec5b95338ce967a", "parameters": [ { "name": "id", "in": "path", "description": "Fiscal Year ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Fiscal year details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/FiscalYear" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Fiscal Years" ], "summary": "Update fiscal year", "description": "Updates an existing fiscal year. Only allowed if status is open.", "operationId": "9fe045aa07032c0551b5e8b0dd2b9bc8", "parameters": [ { "name": "id", "in": "path", "description": "Fiscal Year ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "start_date", "end_date" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" } }, "type": "object" } } } }, "responses": { "200": { "description": "Fiscal year updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/FiscalYear" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/fiscal-years/{id}/close": { "post": { "tags": [ "Fiscal Years" ], "summary": "Close fiscal year", "description": "Runs year-end closing via YearEndCloseService: posts the closing journal entry, hard-locks all periods, and marks the fiscal year closed.", "operationId": "2f01a21584c5933fa1ad29a632fe2aac", "parameters": [ { "name": "id", "in": "path", "description": "Fiscal Year ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Fiscal year closed and closing journal entry posted", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "properties": { "fiscal_year": { "$ref": "#/components/schemas/FiscalYear" }, "closing_journal_entry_id": { "type": "integer", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Fiscal year is already closed, locked, or has unposted entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/fiscal-years/{id}/reopen": { "post": { "tags": [ "Fiscal Years" ], "summary": "Reopen a closed fiscal year", "description": "Sets status back to open and clears locked_at. Only allowed if status is closed (not locked/archived).", "operationId": "e675a23226d8d9b698c83de54059a128", "parameters": [ { "name": "id", "in": "path", "description": "Fiscal Year ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Fiscal year reopened", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/FiscalYear" } }, "type": "object" } } } }, "422": { "description": "Fiscal year must be in closed status to reopen", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/fiscal-years/{id}/lock": { "post": { "tags": [ "Fiscal Years" ], "summary": "Lock fiscal year", "description": "Sets the fiscal year status to locked and records locked_at timestamp. Only allowed if status is closed.", "operationId": "2487e9a9246d8d9c5cf751f070faedd2", "parameters": [ { "name": "id", "in": "path", "description": "Fiscal Year ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Fiscal year locked", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/FiscalYear" } }, "type": "object" } } } }, "422": { "description": "Fiscal year must be closed before locking", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/fixed-assets": { "get": { "tags": [ "Fixed Assets" ], "summary": "List fixed assets", "description": "Returns a paginated list of fixed assets with optional filtering.", "operationId": "a7aaffbc0795f2a80437117132115520", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "active", "fully_depreciated", "disposed" ] } }, { "name": "category", "in": "query", "description": "Filter by category", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of fixed assets", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/FixedAsset" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Fixed Assets" ], "summary": "Create fixed asset", "description": "Creates a new fixed asset. Reference is auto-generated (FA-YYYYMMDD-XXXX), status set to active, book_value set to acquisition_cost.", "operationId": "2538b722539fad095d9631e034ed5b62", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "acquisition_date", "acquisition_cost", "useful_life_months", "depreciation_method" ], "properties": { "name": { "type": "string", "example": "Company Vehicle", "maxLength": 255 }, "category": { "type": "string", "example": "Vehicles", "nullable": true, "maxLength": 100 }, "description": { "type": "string", "nullable": true, "maxLength": 1000 }, "acquisition_date": { "type": "string", "format": "date", "example": "2025-01-01" }, "acquisition_cost": { "type": "number", "format": "float", "example": 50000 }, "residual_value": { "type": "number", "format": "float", "example": 5000, "nullable": true }, "useful_life_months": { "type": "integer", "example": 60, "minimum": 1 }, "depreciation_method": { "type": "string", "example": "straight_line", "enum": [ "straight_line", "declining_balance" ] }, "asset_account_id": { "type": "integer", "nullable": true }, "accumulated_dep_account_id": { "type": "integer", "nullable": true }, "depreciation_expense_account_id": { "type": "integer", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Fixed asset created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/FixedAsset" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/fixed-assets/{id}": { "get": { "tags": [ "Fixed Assets" ], "summary": "Get fixed asset by ID", "description": "Returns a single fixed asset record.", "operationId": "03484de26f2b4d76bf0009d3f6221457", "parameters": [ { "name": "id", "in": "path", "description": "Fixed Asset ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Fixed asset details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/FixedAsset" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Fixed Assets" ], "summary": "Update fixed asset", "description": "Updates an existing fixed asset. Only allowed if status is active.", "operationId": "1b19ec5e5ac07538df736a01e9e48261", "parameters": [ { "name": "id", "in": "path", "description": "Fixed Asset ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "acquisition_date", "acquisition_cost", "useful_life_months", "depreciation_method" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "category": { "type": "string", "nullable": true, "maxLength": 100 }, "description": { "type": "string", "nullable": true, "maxLength": 1000 }, "acquisition_date": { "type": "string", "format": "date" }, "acquisition_cost": { "type": "number", "format": "float" }, "residual_value": { "type": "number", "format": "float", "nullable": true }, "useful_life_months": { "type": "integer", "minimum": 1 }, "depreciation_method": { "type": "string", "enum": [ "straight_line", "declining_balance" ] }, "asset_account_id": { "type": "integer", "nullable": true }, "accumulated_dep_account_id": { "type": "integer", "nullable": true }, "depreciation_expense_account_id": { "type": "integer", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Fixed asset updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/FixedAsset" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Fixed Assets" ], "summary": "Delete fixed asset", "description": "Soft-deletes a fixed asset. Only allowed if status is active.", "operationId": "eb8ff7e44e6b7e6ad86477f3886406f6", "parameters": [ { "name": "id", "in": "path", "description": "Fixed Asset ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Fixed asset deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/fixed-assets/{id}/depreciate": { "post": { "tags": [ "Fixed Assets" ], "summary": "Record depreciation period", "description": "Records one depreciation period for the asset. Updates accumulated_depreciation, book_value, and last_depreciation_date. Sets status to fully_depreciated if book_value reaches residual_value.", "operationId": "c7d42ef20ac0ba662da49409a7dceec1", "parameters": [ { "name": "id", "in": "path", "description": "Fixed Asset ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Depreciation recorded", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/FixedAsset" } }, "type": "object" } } } }, "422": { "description": "Asset is already fully depreciated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/fixed-assets/{id}/dispose": { "post": { "tags": [ "Fixed Assets" ], "summary": "Dispose fixed asset", "description": "Records disposal of a fixed asset. Sets status to disposed and disposal_date to today.", "operationId": "bc95a89c368b199d0281a8a1c98aea02", "parameters": [ { "name": "id", "in": "path", "description": "Fixed Asset ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "disposal_proceeds": { "type": "number", "format": "float", "example": 10000, "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Asset disposed", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/FixedAsset" } }, "type": "object" } } } }, "422": { "description": "Asset is already disposed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/fixed-assets/{id}/depreciation-schedule": { "get": { "tags": [ "Fixed Assets" ], "summary": "Get depreciation schedule", "description": "Returns the full depreciation schedule for a fixed asset.", "operationId": "e31d1157e7da78e592ac5e0e44fa4c54", "parameters": [ { "name": "id", "in": "path", "description": "Fixed Asset ID", "required": true, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "description": "Filter by schedule status", "required": false, "schema": { "type": "string", "enum": [ "scheduled", "posted" ] } } ], "responses": { "200": { "description": "Depreciation schedule", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/fixed-assets/{id}/run-depreciation": { "post": { "tags": [ "Fixed Assets" ], "summary": "Run depreciation for a specific period", "description": "Posts the depreciation journal entry for one asset for the given period (YYYY-MM). Updates the depreciation schedule and asset book value.", "operationId": "21a5b15c41eba8d846f43a2dec75ce0d", "parameters": [ { "name": "id", "in": "path", "description": "Fixed Asset ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "period" ], "properties": { "period": { "description": "Depreciation period in YYYY-MM format", "type": "string", "example": "2025-03" } }, "type": "object" } } } }, "responses": { "200": { "description": "Depreciation posted", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Asset not active or no scheduled entry for period", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/fixed-assets/run-depreciation": { "post": { "tags": [ "Fixed Assets" ], "summary": "Bulk run depreciation for all active assets", "description": "Posts depreciation for ALL active fixed assets in the company for the given period. Returns counts of posted, skipped, and errored assets.", "operationId": "6603651dfb79a0776f06128484ac3202", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "period" ], "properties": { "period": { "description": "Depreciation period in YYYY-MM format", "type": "string", "example": "2025-03" } }, "type": "object" } } } }, "responses": { "200": { "description": "Bulk depreciation result", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "properties": { "period": { "type": "string", "example": "2025-03" }, "posted": { "type": "integer" }, "skipped": { "type": "integer" }, "errors": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/goods-received-notes": { "get": { "tags": [ "Goods Received Notes" ], "summary": "List goods received notes", "description": "Returns a paginated list of GRNs with optional filtering.", "operationId": "d4defdf95f4f2819cae939236bf256dd", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "purchase_order_id", "in": "query", "description": "Filter by purchase order ID", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "draft", "validated" ] } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of GRNs", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/GoodsReceivedNote" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Goods Received Notes" ], "summary": "Create GRN", "description": "Creates a new goods received note in draft status.", "operationId": "aca3808d02dae05215d6e8a5b4f1a0e1", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "warehouse_id", "received_date", "lines" ], "properties": { "purchase_order_id": { "type": "integer", "nullable": true }, "warehouse_id": { "type": "integer", "example": 1 }, "received_date": { "type": "string", "format": "date", "example": "2024-01-15" }, "notes": { "type": "string", "nullable": true, "maxLength": 1000 }, "lines": { "type": "array", "items": { "properties": { "product_id": { "type": "integer", "example": 1 }, "purchase_order_line_id": { "type": "integer", "nullable": true }, "quantity_received": { "type": "number", "format": "float", "example": 5 }, "unit_cost": { "type": "number", "format": "float", "nullable": true } }, "type": "object" }, "minItems": 1 } }, "type": "object" } } } }, "responses": { "201": { "description": "GRN created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/GoodsReceivedNote" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/goods-received-notes/{id}": { "get": { "tags": [ "Goods Received Notes" ], "summary": "Get GRN by ID", "description": "Returns a single goods received note with its line items.", "operationId": "53ec7ce7d9e0e5ad12672bc73128fdac", "parameters": [ { "name": "id", "in": "path", "description": "GRN ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "GRN details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/GoodsReceivedNote" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Goods Received Notes" ], "summary": "Update GRN", "description": "Updates a draft goods received note and replaces its lines.", "operationId": "2b04a79d8d9fe5621c8a7236f650e66a", "parameters": [ { "name": "id", "in": "path", "description": "GRN ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "warehouse_id", "received_date", "lines" ], "properties": { "purchase_order_id": { "type": "integer", "nullable": true }, "warehouse_id": { "type": "integer" }, "received_date": { "type": "string", "format": "date" }, "notes": { "type": "string", "nullable": true, "maxLength": 1000 }, "lines": { "type": "array", "items": { "properties": { "product_id": { "type": "integer" }, "purchase_order_line_id": { "type": "integer", "nullable": true }, "quantity_received": { "type": "number", "format": "float" }, "unit_cost": { "type": "number", "format": "float", "nullable": true } }, "type": "object" }, "minItems": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "GRN updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/GoodsReceivedNote" } }, "type": "object" } } } }, "400": { "description": "Cannot update non-draft GRN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Goods Received Notes" ], "summary": "Delete GRN", "description": "Deletes a draft goods received note.", "operationId": "2c4109f619e8641c44853499f90b87ec", "parameters": [ { "name": "id", "in": "path", "description": "GRN ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "GRN deleted" }, "400": { "description": "Cannot delete non-draft GRN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/goods-received-notes/{id}/validate": { "post": { "tags": [ "Goods Received Notes" ], "summary": "Validate GRN", "description": "Marks a draft goods received note as validated.", "operationId": "92c1357fa6e41ff906adc82d24a21ab8", "parameters": [ { "name": "id", "in": "path", "description": "GRN ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "GRN validated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/GoodsReceivedNote" } }, "type": "object" } } } }, "400": { "description": "GRN is already validated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/goods-received-notes/{id}/post": { "post": { "tags": [ "Goods Received Notes" ], "summary": "Post GRN", "description": "Posts a validated goods received note, setting its status to posted.", "operationId": "ff9376a089b641eac69b87780d9617ca", "parameters": [ { "name": "id", "in": "path", "description": "GRN ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "GRN posted", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/GoodsReceivedNote" } }, "type": "object" } } } }, "422": { "description": "GRN is not in validated status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/gosi": { "get": { "tags": [ "GOSI" ], "summary": "List GOSI monthly submissions", "description": "Returns a paginated list of GOSI monthly submissions.", "operationId": "1d62deceee64a74c6603d0790042cd7d", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "year", "in": "query", "description": "Filter by year", "required": false, "schema": { "type": "integer", "example": 2026 } }, { "name": "month", "in": "query", "description": "Filter by month (1-12)", "required": false, "schema": { "type": "integer", "maximum": 12, "minimum": 1 } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "draft", "compiled", "submitted", "accepted", "rejected", "paid" ] } } ], "responses": { "200": { "description": "Paginated list of GOSI submissions", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/GosiSubmission" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/gosi/{id}": { "get": { "tags": [ "GOSI" ], "summary": "Get GOSI submission by ID", "description": "Returns a single GOSI submission with all employee contribution lines.", "operationId": "ce8a2bbd5a068bc94e66faec39cb6b3b", "parameters": [ { "name": "id", "in": "path", "description": "Submission ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "GOSI submission details with lines", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/GosiSubmission" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/gosi/generate": { "post": { "tags": [ "GOSI" ], "summary": "Generate GOSI monthly submission", "description": "Compiles the monthly GOSI submission for all active employees, creates contribution lines, and posts a draft journal entry.", "operationId": "0d45ec5bd59a62a7a7a0d023230b95d9", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "year", "month" ], "properties": { "year": { "type": "integer", "example": 2026, "maximum": 2100, "minimum": 2000 }, "month": { "type": "integer", "example": 5, "maximum": 12, "minimum": 1 } }, "type": "object" } } } }, "responses": { "201": { "description": "GOSI submission generated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/GosiSubmission" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/gosi/{id}/submit": { "post": { "tags": [ "GOSI" ], "summary": "Submit GOSI to authority", "description": "Submits the compiled GOSI monthly submission to the GOSI authority API and marks it as submitted.", "operationId": "4bbfae2260b0376cac976e500c2b683c", "parameters": [ { "name": "id", "in": "path", "description": "Submission ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "GOSI submission submitted", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/GosiSubmission" } }, "type": "object" } } } }, "422": { "description": "Submission cannot be submitted in current status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/gosi/{id}/export": { "get": { "tags": [ "GOSI" ], "summary": "Export GOSI submission as WPS/Mudad CSV", "description": "Downloads the GOSI submission in Mudad WPS CSV format for upload to the GOSI portal.", "operationId": "f0e47f7dc3f1971441e671d966614914", "parameters": [ { "name": "id", "in": "path", "description": "Submission ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "CSV file download" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/inventory": { "get": { "tags": [ "Inventory" ], "summary": "List stock movements", "description": "Returns a paginated list of stock movements with optional filtering.", "operationId": "c8531fd69cc0a7d2d0871100b39ee284", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Search by product name", "required": false, "schema": { "type": "string" } }, { "name": "product_id", "in": "query", "description": "Filter by product ID", "required": false, "schema": { "type": "integer" } }, { "name": "state", "in": "query", "description": "Filter by state", "required": false, "schema": { "type": "string", "enum": [ "draft", "confirmed", "done", "cancelled" ] } }, { "name": "from", "in": "query", "description": "Filter from date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Filter to date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of stock movements", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/StockMove" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Inventory" ], "summary": "Create stock movement", "description": "Creates a new stock movement record.", "operationId": "60ffc5cf7058061dd1723b1e2946b534", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "product_id", "quantity" ], "properties": { "product_id": { "type": "integer", "example": 1 }, "from_location_id": { "type": "integer", "example": 1, "nullable": true }, "to_location_id": { "type": "integer", "example": 2, "nullable": true }, "quantity": { "type": "number", "format": "float", "example": 10, "minimum": 0.001 }, "unit_cost": { "type": "number", "format": "float", "example": 1800, "nullable": true }, "total_cost": { "type": "number", "format": "float", "example": 18000, "nullable": true }, "serial_number": { "type": "string", "nullable": true, "maxLength": 255 }, "lot_number": { "type": "string", "nullable": true, "maxLength": 255 }, "expiry_date": { "type": "string", "format": "date", "nullable": true }, "source_type": { "type": "string", "example": "purchase_order", "nullable": true, "maxLength": 100 }, "source_id": { "type": "integer", "example": 1, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Stock movement created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/StockMove" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/inventory/{id}": { "get": { "tags": [ "Inventory" ], "summary": "Get stock movement by ID", "description": "Returns a single stock movement record.", "operationId": "b86fa1beb2cb03623824451c7ad6aeab", "parameters": [ { "name": "id", "in": "path", "description": "Stock move ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Stock movement details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/StockMove" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/inventory/{id}/process": { "post": { "tags": [ "Inventory" ], "summary": "Process stock movement", "description": "Marks a confirmed stock movement as done.", "operationId": "d595646ec61b37b65d4306e54b909b01", "parameters": [ { "name": "id", "in": "path", "description": "Stock move ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Stock movement processed", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/StockMove" } }, "type": "object" } } } }, "422": { "description": "Stock move is not in confirmed state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/invoices": { "get": { "tags": [ "Invoices" ], "summary": "List invoices", "description": "Returns a paginated list of customer invoices with optional search and filtering.", "operationId": "176f86601dff5362250710476b314be6", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Search by reference or customer name", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "draft", "posted", "sent", "paid", "cancelled" ] } }, { "name": "customer_id", "in": "query", "description": "Filter by customer ID", "required": false, "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of invoices", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Invoices" ], "summary": "Create invoice", "description": "Creates a new customer invoice.", "operationId": "032630ac969f519682d839297c530d5c", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "customer_id" ], "properties": { "customer_id": { "type": "integer", "example": 1 }, "currency_id": { "type": "integer", "example": 1, "nullable": true }, "exchange_rate": { "type": "number", "format": "float", "example": 1, "nullable": true }, "invoice_date": { "type": "string", "format": "date", "example": "2024-01-15", "nullable": true }, "due_date": { "type": "string", "format": "date", "example": "2024-02-15", "nullable": true }, "type": { "type": "string", "example": "standard", "nullable": true, "maxLength": 50 }, "subtotal": { "type": "number", "format": "float", "example": 1000, "nullable": true }, "discount_amount": { "type": "number", "format": "float", "example": 0, "nullable": true }, "tax_amount": { "type": "number", "format": "float", "example": 150, "nullable": true }, "total": { "type": "number", "format": "float", "example": 1150, "nullable": true }, "notes": { "type": "string", "nullable": true, "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Invoice created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/Invoice" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/invoices/{id}": { "get": { "tags": [ "Invoices" ], "summary": "Get invoice by ID", "description": "Returns a single invoice record with line items.", "operationId": "9d266eac4a087db1ce1b1a88a27c5864", "parameters": [ { "name": "id", "in": "path", "description": "Invoice ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Invoice details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Invoice" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Invoices" ], "summary": "Update invoice", "description": "Updates an existing invoice. Only draft invoices can be edited.", "operationId": "7ec124e53679451f551e7d5f3ed9deea", "parameters": [ { "name": "id", "in": "path", "description": "Invoice ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "customer_id" ], "properties": { "customer_id": { "type": "integer", "example": 1 }, "currency_id": { "type": "integer", "nullable": true }, "exchange_rate": { "type": "number", "format": "float", "nullable": true }, "invoice_date": { "type": "string", "format": "date", "nullable": true }, "due_date": { "type": "string", "format": "date", "nullable": true }, "type": { "type": "string", "nullable": true, "maxLength": 50 }, "subtotal": { "type": "number", "format": "float", "nullable": true }, "discount_amount": { "type": "number", "format": "float", "nullable": true }, "tax_amount": { "type": "number", "format": "float", "nullable": true }, "total": { "type": "number", "format": "float", "nullable": true }, "notes": { "type": "string", "nullable": true, "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Invoice updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Invoice" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Invoices" ], "summary": "Delete invoice", "description": "Soft-deletes a draft invoice.", "operationId": "056695bac32ace10c9dec32991fad318", "parameters": [ { "name": "id", "in": "path", "description": "Invoice ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Invoice deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/invoices/{id}/post": { "post": { "tags": [ "Invoices" ], "summary": "Post invoice", "description": "Transitions a draft invoice to posted status, making it ready to send.", "operationId": "28520e837ab544543c2224f88faf8646", "parameters": [ { "name": "id", "in": "path", "description": "Invoice ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Invoice posted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Invoice" } }, "type": "object" } } } }, "422": { "description": "Invoice is not in draft status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/invoices/{id}/send": { "post": { "tags": [ "Invoices" ], "summary": "Send invoice", "description": "Marks a posted invoice as sent to the customer.", "operationId": "544d2b432d83bc7e392cdaac18c50b93", "parameters": [ { "name": "id", "in": "path", "description": "Invoice ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Invoice marked as sent", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Invoice" } }, "type": "object" } } } }, "422": { "description": "Invoice must be in posted status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/invoices/{id}/credit-note": { "post": { "tags": [ "Invoices" ], "summary": "Create credit note", "description": "Creates a credit note (reversal invoice) for a posted or sent invoice.", "operationId": "d18ad422620e1673b1bd37e440fc3d91", "parameters": [ { "name": "id", "in": "path", "description": "Invoice ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "amount" ], "properties": { "amount": { "description": "Credit amount (must not exceed amount_due)", "type": "number", "format": "float", "example": 100 }, "reason": { "type": "string", "example": "Damaged goods", "nullable": true, "maxLength": 1000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Credit note created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Invoice" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/invoices/{id}/pdf": { "get": { "tags": [ "Invoices" ], "summary": "Get invoice PDF URL", "description": "Returns the download URL for the invoice PDF.", "operationId": "47c05032a325130bb79f5b1b4db58f9f", "parameters": [ { "name": "id", "in": "path", "description": "Invoice ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "PDF download URL", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "properties": { "url": { "type": "string", "format": "uri", "example": "https://app.example.com/pdf/invoices/1" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/invoices/{id}/lines": { "get": { "tags": [ "Invoices" ], "summary": "Get invoice lines", "description": "Returns the line items for a specific invoice.", "operationId": "da50aaaa26e7f51258a2faae0f9e9acf", "parameters": [ { "name": "id", "in": "path", "description": "Invoice ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Invoice line items", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "product_id": { "type": "integer", "example": 1, "nullable": true }, "description": { "type": "string", "example": "Laptop Pro" }, "quantity": { "type": "number", "format": "float", "example": 2 }, "unit_price": { "type": "number", "format": "float", "example": 2500 }, "discount": { "type": "number", "format": "float", "example": 0 }, "tax_rate": { "type": "number", "format": "float", "example": 15 }, "total": { "type": "number", "format": "float", "example": 5750 } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/invoices/{id}/aging": { "get": { "tags": [ "Invoices" ], "summary": "Get invoice aging details", "description": "Returns aging information for a specific invoice including days overdue and aging bucket.", "operationId": "eb98bffa8680dfb4e723a92349394f21", "parameters": [ { "name": "id", "in": "path", "description": "Invoice ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Invoice aging details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "properties": { "invoice_id": { "type": "integer", "example": 1 }, "reference": { "type": "string", "example": "INV-2024-00001" }, "customer_name": { "type": "string", "example": "Acme Corp" }, "invoice_date": { "type": "string", "format": "date", "example": "2024-01-15" }, "due_date": { "type": "string", "format": "date", "example": "2024-02-15" }, "total": { "type": "number", "format": "float", "example": 1150 }, "amount_due": { "type": "number", "format": "float", "example": 1150 }, "days_overdue": { "description": "Negative means not yet due", "type": "integer", "example": 30 }, "aging_bucket": { "type": "string", "example": "1-30", "enum": [ "current", "1-30", "31-60", "61-90", "90+" ] } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/invoices/aging-summary": { "get": { "tags": [ "Invoices" ], "summary": "Get aging summary for all outstanding invoices", "description": "Returns a paginated list of all invoices with outstanding balances, including aging bucket information.", "operationId": "1d3e4dbbd50506b3a97aefe931bf2485", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "customer_id", "in": "query", "description": "Filter by customer ID", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Paginated aging summary", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/journal-entries": { "get": { "tags": [ "Journal Entries" ], "summary": "List journal entries", "description": "Returns a paginated list of journal entries with optional filtering.", "operationId": "ed14d1ec477a145e5f1d708fafda75c0", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Search by description", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "draft", "posted", "reversed" ] } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of journal entries", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/JournalEntry" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Journal Entries" ], "summary": "Create journal entry", "description": "Creates a new journal entry.", "operationId": "4b1e4b0fe06650ae84bfe8a2a57bc67a", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "description" ], "properties": { "entry_date": { "type": "string", "format": "date", "example": "2024-01-15", "nullable": true }, "description": { "type": "string", "example": "Monthly closing entry", "maxLength": 1000 }, "reference": { "type": "string", "nullable": true, "maxLength": 255 }, "currency_id": { "type": "integer", "example": 1, "nullable": true }, "exchange_rate": { "type": "number", "format": "float", "example": 1, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Journal entry created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/JournalEntry" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/journal-entries/{id}": { "get": { "tags": [ "Journal Entries" ], "summary": "Get journal entry by ID", "description": "Returns a single journal entry with transaction lines.", "operationId": "dbf5c8b72c884a2c298baedd48b19b6c", "parameters": [ { "name": "id", "in": "path", "description": "Journal entry ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Journal entry details with transaction lines", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/JournalEntry" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Journal Entries" ], "summary": "Update journal entry", "description": "Updates a draft journal entry.", "operationId": "8c3e265070bbda4befaac2fa0a1ebff6", "parameters": [ { "name": "id", "in": "path", "description": "Journal entry ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "description" ], "properties": { "entry_date": { "type": "string", "format": "date", "nullable": true }, "description": { "type": "string", "maxLength": 1000 }, "reference": { "type": "string", "nullable": true, "maxLength": 255 }, "currency_id": { "type": "integer", "nullable": true }, "exchange_rate": { "type": "number", "format": "float", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Journal entry updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/JournalEntry" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/journal-entries/{id}/post": { "post": { "tags": [ "Journal Entries" ], "summary": "Post journal entry", "description": "Transitions a draft journal entry to posted status, making it immutable.", "operationId": "22a5488c056e8b908d33d2930a687e85", "parameters": [ { "name": "id", "in": "path", "description": "Journal entry ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Journal entry posted", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/JournalEntry" } }, "type": "object" } } } }, "422": { "description": "Entry is not in draft status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/journal-entries/{id}/reverse": { "post": { "tags": [ "Journal Entries" ], "summary": "Reverse journal entry", "description": "Creates a reversing entry for a posted journal entry.", "operationId": "7c309ea5b41a9a95c9c6fa05b7455987", "parameters": [ { "name": "id", "in": "path", "description": "Journal entry ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Journal entry reversed", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/JournalEntry" } }, "type": "object" } } } }, "422": { "description": "Entry must be in posted status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/journal-entries/{id}/lines": { "get": { "tags": [ "Journal Entries" ], "summary": "Get journal entry lines", "description": "Returns the transaction lines (debits/credits) for a journal entry.", "operationId": "ff5334a7e821e722df3f6b4ca4676351", "parameters": [ { "name": "id", "in": "path", "description": "Journal entry ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Transaction lines", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "account_id": { "type": "integer", "example": 10 }, "account_code": { "type": "string", "example": "1010", "nullable": true }, "account_name": { "type": "string", "example": "Cash", "nullable": true }, "type": { "type": "string", "example": "debit", "enum": [ "debit", "credit" ] }, "amount": { "type": "number", "format": "float", "example": 1000 }, "currency_id": { "type": "integer", "example": 1, "nullable": true }, "description": { "type": "string", "nullable": true }, "cost_center_id": { "type": "integer", "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/leads": { "get": { "tags": [ "Leads" ], "summary": "List leads", "description": "Returns a paginated list of CRM leads with optional filtering.", "operationId": "9e77b2ec804bfaef99ad6b5e07fef702", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Search by title, contact name, or company name", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "new", "contacted", "qualified", "lost", "converted" ] } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of leads", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Lead" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Leads" ], "summary": "Create lead", "description": "Creates a new CRM lead.", "operationId": "a72f7afdf86aeae8cf04b87c89f9c0ab", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title" ], "properties": { "title": { "type": "string", "example": "Enterprise Software Deal", "maxLength": 255 }, "contact_name": { "type": "string", "example": "John Smith", "nullable": true, "maxLength": 255 }, "contact_email": { "type": "string", "format": "email", "example": "john@prospect.com", "nullable": true }, "contact_phone": { "type": "string", "example": "+966500000003", "nullable": true, "maxLength": 50 }, "company_name": { "type": "string", "example": "Prospect Ltd", "nullable": true, "maxLength": 255 }, "status": { "type": "string", "example": "new", "nullable": true, "maxLength": 50 }, "expected_value": { "type": "number", "format": "float", "example": 50000, "nullable": true }, "expected_close_date": { "type": "string", "format": "date", "example": "2024-06-30", "nullable": true }, "assigned_to": { "type": "integer", "nullable": true }, "notes": { "type": "string", "nullable": true, "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Lead created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/Lead" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/leads/{id}": { "get": { "tags": [ "Leads" ], "summary": "Get lead by ID", "description": "Returns a single lead record.", "operationId": "95d2deb2d9dd5fb217a1c75a54d4f7c9", "parameters": [ { "name": "id", "in": "path", "description": "Lead ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Lead details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Lead" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Leads" ], "summary": "Update lead", "description": "Updates an existing lead record.", "operationId": "6251a018fe996dd3ed6649dceb6e5315", "parameters": [ { "name": "id", "in": "path", "description": "Lead ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title" ], "properties": { "title": { "type": "string", "maxLength": 255 }, "contact_name": { "type": "string", "nullable": true, "maxLength": 255 }, "contact_email": { "type": "string", "format": "email", "nullable": true }, "contact_phone": { "type": "string", "nullable": true, "maxLength": 50 }, "company_name": { "type": "string", "nullable": true, "maxLength": 255 }, "status": { "type": "string", "nullable": true, "maxLength": 50 }, "expected_value": { "type": "number", "format": "float", "nullable": true }, "expected_close_date": { "type": "string", "format": "date", "nullable": true }, "assigned_to": { "type": "integer", "nullable": true }, "notes": { "type": "string", "nullable": true, "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Lead updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Lead" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Leads" ], "summary": "Delete lead", "description": "Soft-deletes a lead record.", "operationId": "c8ae9bfe4cbecc309a79038ea526b3d3", "parameters": [ { "name": "id", "in": "path", "description": "Lead ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Lead deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/leads/{id}/convert": { "post": { "tags": [ "Leads" ], "summary": "Convert lead to opportunity", "description": "Marks a lead as converted.", "operationId": "7fdc7861e36b7e3ec59877f6faf336a0", "parameters": [ { "name": "id", "in": "path", "description": "Lead ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Lead converted", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Lead" } }, "type": "object" } } } }, "422": { "description": "Lead has already been converted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/leads/{id}/disqualify": { "post": { "tags": [ "Leads" ], "summary": "Disqualify lead", "description": "Marks a lead as disqualified with an optional reason. Cannot disqualify a lead that is already disqualified or converted.", "operationId": "0c9a8b391bf784185cf51c1565af4957", "parameters": [ { "name": "id", "in": "path", "description": "Lead ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "reason": { "description": "Reason for disqualification", "type": "string", "example": "Budget constraints", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Lead disqualified", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Lead" } }, "type": "object" } } } }, "422": { "description": "Lead is already disqualified or converted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/leave-balances": { "get": { "tags": [ "Leave Balances" ], "summary": "List leave balances", "description": "Returns a paginated list of leave balances with optional filtering.", "operationId": "f78519932e9e097f9ab9478c63dfa8ed", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "employee_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "leave_type_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "year", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Paginated list of leave balances" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/leave-balances/{id}": { "get": { "tags": [ "Leave Balances" ], "summary": "Get leave balance by ID", "operationId": "cc60413310f6c3077a5abc32b0a47df8", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Leave balance details" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/leave-balances/allocate": { "post": { "tags": [ "Leave Balances" ], "summary": "Allocate or update a leave balance", "description": "Creates or updates a leave balance record for an employee, leave type, and year.", "operationId": "28413512f58e66b4ca4ee5bfef4c4aa0", "responses": { "200": { "description": "Leave balance allocated or updated" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/leave-balances/{id}/adjust": { "post": { "tags": [ "Leave Balances" ], "summary": "Adjust a leave balance", "description": "Adjusts the remaining days for a leave balance. Positive values add days, negative values deduct.", "operationId": "bb6a26839365bcdb2250f4d670f03481", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Leave balance adjusted" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/leaves": { "get": { "tags": [ "Leave Requests" ], "summary": "List leave requests", "description": "Returns a paginated list of leave requests with optional filtering.", "operationId": "ab4aad647ad52c2d986c956a2afd0193", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Search by employee name", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "cancelled" ] } }, { "name": "employee_id", "in": "query", "description": "Filter by employee ID", "required": false, "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of leave requests", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeaveRequest" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Leave Requests" ], "summary": "Create leave request", "description": "Creates a new employee leave request.", "operationId": "301eb78c41e42172f6a6cfc8590414c2", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "employee_id", "leave_type_id", "start_date", "end_date" ], "properties": { "employee_id": { "type": "integer", "example": 1 }, "leave_type_id": { "type": "integer", "example": 1 }, "start_date": { "type": "string", "format": "date", "example": "2024-03-01" }, "end_date": { "type": "string", "format": "date", "example": "2024-03-07" }, "days_requested": { "type": "number", "format": "float", "example": 5, "nullable": true }, "reason": { "type": "string", "example": "Family vacation", "nullable": true, "maxLength": 2000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Leave request created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/LeaveRequest" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/leaves/{id}": { "get": { "tags": [ "Leave Requests" ], "summary": "Get leave request by ID", "description": "Returns a single leave request record.", "operationId": "b00500d459f04045971dc3289492bcfb", "parameters": [ { "name": "id", "in": "path", "description": "Leave request ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Leave request details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/LeaveRequest" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Leave Requests" ], "summary": "Update leave request", "description": "Updates a pending leave request.", "operationId": "5b87d0a6b2a63703a6f059c7555b6902", "parameters": [ { "name": "id", "in": "path", "description": "Leave request ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "employee_id", "leave_type_id", "start_date", "end_date" ], "properties": { "employee_id": { "type": "integer" }, "leave_type_id": { "type": "integer" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "days_requested": { "type": "number", "format": "float", "nullable": true }, "reason": { "type": "string", "nullable": true, "maxLength": 2000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Leave request updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/LeaveRequest" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/leaves/{id}/approve": { "post": { "tags": [ "Leave Requests" ], "summary": "Approve leave request", "description": "Approves a pending leave request.", "operationId": "c5db9f26181ceb535896a9f7ec453a93", "parameters": [ { "name": "id", "in": "path", "description": "Leave request ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Leave request approved", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/LeaveRequest" } }, "type": "object" } } } }, "422": { "description": "Request cannot be approved in current status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/leaves/{id}/reject": { "post": { "tags": [ "Leave Requests" ], "summary": "Reject leave request", "description": "Rejects a pending leave request with an optional reason.", "operationId": "4f5b0cb3e6b1fef5c2ad35938c0d7648", "parameters": [ { "name": "id", "in": "path", "description": "Leave request ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "rejection_reason": { "type": "string", "example": "Business critical period", "nullable": true, "maxLength": 2000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Leave request rejected", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/LeaveRequest" } }, "type": "object" } } } }, "422": { "description": "Request cannot be rejected in current status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/leave-accrual/run": { "post": { "tags": [ "Leave Accrual" ], "summary": "Run leave accrual", "description": "Runs monthly leave accrual for all or specific employees. Returns count of balances updated.", "operationId": "5237903b938edfba97d18833cdc9fed0", "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "as_of_date": { "description": "Accrual month date, defaults to today", "type": "string", "format": "date", "example": "2026-05-01", "nullable": true }, "employee_id": { "description": "Specific employee ID; omit for all employees", "type": "integer", "example": 5, "nullable": true }, "leave_type_id": { "description": "Specific leave type ID (not currently used by service, reserved for future filtering)", "type": "integer", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Accrual completed", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "properties": { "accrued": { "type": "integer", "example": 42 }, "skipped": { "type": "integer", "example": 3 }, "errors": { "type": "integer", "example": 0 } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/leave-accrual/preview": { "get": { "tags": [ "Leave Accrual" ], "summary": "Preview leave accrual (dry run)", "description": "Returns what leave accrual WOULD be for all or specific employees without persisting any changes.", "operationId": "45da4c5dedb9cbc85edd463874e1baf0", "parameters": [ { "name": "as_of_date", "in": "query", "description": "Accrual month date, defaults to today", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "employee_id", "in": "query", "description": "Specific employee ID; omit for all", "required": false, "schema": { "type": "integer" } }, { "name": "leave_type_id", "in": "query", "description": "Filter by leave type ID", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Preview of accrual that would occur", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "array", "items": { "properties": { "employee_id": { "type": "integer", "example": 1 }, "employee_name": { "type": "string", "example": "Ahmed Al-Rashid" }, "annual_days_entitlement": { "type": "integer", "example": 21 }, "monthly_accrual": { "type": "number", "format": "float", "example": 1.75 }, "would_skip": { "type": "boolean", "example": false } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/leave-types": { "get": { "tags": [ "Leave Types" ], "summary": "List leave types", "description": "Returns a paginated list of leave types with optional is_active filter.", "operationId": "40ed30931c6d3d9edddc1fdf477ac447", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "is_active", "in": "query", "description": "Filter by active status", "required": false, "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of leave types", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeaveType" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Leave Types" ], "summary": "Create leave type", "description": "Creates a new leave type.", "operationId": "97472685b347766578c0e18f0365c9a9", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "days_allowed" ], "properties": { "name": { "type": "string", "example": "Annual Leave", "maxLength": 255 }, "days_allowed": { "type": "integer", "example": 21, "minimum": 1 }, "is_paid": { "type": "boolean", "example": true }, "requires_approval": { "type": "boolean", "example": true }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Leave type created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/LeaveType" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/leave-types/{id}": { "get": { "tags": [ "Leave Types" ], "summary": "Get leave type by ID", "description": "Returns a single leave type record.", "operationId": "2ff47ecd7b357933214d54affe84ad54", "parameters": [ { "name": "id", "in": "path", "description": "Leave Type ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Leave type details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/LeaveType" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Leave Types" ], "summary": "Update leave type", "description": "Updates an existing leave type.", "operationId": "18f4d858f3ef6a093a442542443fb1b4", "parameters": [ { "name": "id", "in": "path", "description": "Leave Type ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "days_allowed" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "days_allowed": { "type": "integer", "minimum": 1 }, "is_paid": { "type": "boolean" }, "requires_approval": { "type": "boolean" }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Leave type updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/LeaveType" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Leave Types" ], "summary": "Delete leave type", "description": "Deletes a leave type record.", "operationId": "2653698b311bb3c21c2a1f8f0942bea7", "parameters": [ { "name": "id", "in": "path", "description": "Leave Type ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Leave type deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/opening-balances": { "get": { "tags": [ "Opening Balances" ], "summary": "List opening balance journal entries", "description": "Returns a paginated list of journal entries flagged as opening balances.", "operationId": "ec020f8b518bd6e1bbe28fc82b667459", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100 } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "default": "entry_date" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of opening balance entries", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Opening Balances" ], "summary": "Import opening balances", "description": "Posts a balanced opening balance journal entry. The service auto-balances via the Opening Balance Equity account (code 3999).", "operationId": "f1cc6b9253f028957d86a8164b670c8b", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "as_of_date", "entries" ], "properties": { "as_of_date": { "description": "Go-live / migration date", "type": "string", "format": "date", "example": "2025-01-01" }, "entries": { "description": "Array of account balances (amount is always positive; sign inferred from account normal_balance)", "type": "array", "items": { "required": [ "account_id", "amount" ], "properties": { "account_id": { "type": "integer", "example": 10 }, "amount": { "type": "number", "format": "float", "example": 5000 } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Opening balances posted", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/opening-balances/{id}": { "get": { "tags": [ "Opening Balances" ], "summary": "Get opening balance entry by ID", "description": "Returns a single opening balance journal entry with transaction lines.", "operationId": "08da73ddfec8b13adf25154ddec1b02c", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Opening balance entry details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/opportunity-activities": { "get": { "tags": [ "Opportunity Activities" ], "summary": "List opportunity activities", "description": "Returns a paginated list of opportunity activities with optional filtering.", "operationId": "01b5015137653dd36ec55be488e558f5", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "opportunity_id", "in": "query", "description": "Filter by opportunity ID", "required": false, "schema": { "type": "integer" } }, { "name": "type", "in": "query", "description": "Filter by activity type", "required": false, "schema": { "type": "string", "enum": [ "note", "call", "email", "meeting", "task" ] } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of opportunity activities", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpportunityActivity" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Opportunity Activities" ], "summary": "Create opportunity activity", "description": "Creates a new activity linked to an opportunity.", "operationId": "6db277282369e29d3187bc45069c65e9", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "opportunity_id", "type", "title" ], "properties": { "opportunity_id": { "type": "integer", "example": 1 }, "type": { "type": "string", "example": "call", "enum": [ "note", "call", "email", "meeting", "task" ] }, "title": { "type": "string", "example": "Follow-up call", "maxLength": 255 }, "description": { "type": "string", "nullable": true, "maxLength": 2000 }, "scheduled_at": { "type": "string", "format": "date", "example": "2024-01-20", "nullable": true }, "completed_at": { "type": "string", "format": "date", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Activity created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/OpportunityActivity" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/opportunity-activities/{id}": { "get": { "tags": [ "Opportunity Activities" ], "summary": "Get opportunity activity by ID", "description": "Returns a single opportunity activity record.", "operationId": "57b624ef00179d2aedfc8a7bba6b495c", "parameters": [ { "name": "id", "in": "path", "description": "Activity ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Activity details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/OpportunityActivity" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Opportunity Activities" ], "summary": "Update opportunity activity", "description": "Updates an existing opportunity activity.", "operationId": "57732f5926965c192e0ff7e0c07accdd", "parameters": [ { "name": "id", "in": "path", "description": "Activity ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "opportunity_id", "type", "title" ], "properties": { "opportunity_id": { "type": "integer" }, "type": { "type": "string", "enum": [ "note", "call", "email", "meeting", "task" ] }, "title": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "nullable": true, "maxLength": 2000 }, "scheduled_at": { "type": "string", "format": "date", "nullable": true }, "completed_at": { "type": "string", "format": "date", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Activity updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/OpportunityActivity" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Opportunity Activities" ], "summary": "Delete opportunity activity", "description": "Deletes an opportunity activity record.", "operationId": "497b8907c5647d120bab00166335320b", "parameters": [ { "name": "id", "in": "path", "description": "Activity ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Activity deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/opportunity-activities/{id}/complete": { "post": { "tags": [ "Opportunity Activities" ], "summary": "Complete an activity", "description": "Marks an opportunity activity as completed.", "operationId": "782dd0dc0f52b5d4479269ae828a0b1a", "parameters": [ { "name": "id", "in": "path", "description": "Activity ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Activity completed", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/OpportunityActivity" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/opportunities": { "get": { "tags": [ "Opportunities" ], "summary": "List opportunities", "description": "Returns a paginated list of CRM opportunities with optional filtering.", "operationId": "d68e0ee540ed0d175ebe5a459c64cb34", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Search by title", "required": false, "schema": { "type": "string" } }, { "name": "stage", "in": "query", "description": "Filter by stage", "required": false, "schema": { "type": "string", "enum": [ "qualified", "proposal", "negotiation", "won", "lost" ] } }, { "name": "customer_id", "in": "query", "description": "Filter by customer ID", "required": false, "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of opportunities", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Opportunity" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Opportunities" ], "summary": "Create opportunity", "description": "Creates a new CRM opportunity.", "operationId": "fbd2ae2508970a5bc7ca310f71d15fef", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title" ], "properties": { "title": { "type": "string", "example": "Enterprise License Deal", "maxLength": 255 }, "lead_id": { "type": "integer", "nullable": true }, "customer_id": { "type": "integer", "example": 1, "nullable": true }, "stage": { "type": "string", "example": "qualified", "nullable": true, "enum": [ "qualified", "proposal", "negotiation", "won", "lost" ] }, "probability": { "type": "integer", "example": 30, "nullable": true, "maximum": 100, "minimum": 0 }, "expected_value": { "type": "number", "format": "float", "example": 100000, "nullable": true }, "currency_id": { "type": "integer", "example": 1, "nullable": true }, "expected_close_date": { "type": "string", "format": "date", "example": "2024-06-30", "nullable": true }, "assigned_to": { "type": "integer", "nullable": true }, "quote_id": { "type": "integer", "nullable": true }, "description": { "type": "string", "nullable": true, "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Opportunity created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/Opportunity" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/opportunities/{id}": { "get": { "tags": [ "Opportunities" ], "summary": "Get opportunity by ID", "description": "Returns a single opportunity record.", "operationId": "8f0b22eb8add3e5a35a34e4244517848", "parameters": [ { "name": "id", "in": "path", "description": "Opportunity ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Opportunity details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Opportunity" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Opportunities" ], "summary": "Update opportunity", "description": "Updates an existing opportunity.", "operationId": "6b508608849c9fbb3a681d9346a0636f", "parameters": [ { "name": "id", "in": "path", "description": "Opportunity ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title" ], "properties": { "title": { "type": "string", "maxLength": 255 }, "lead_id": { "type": "integer", "nullable": true }, "customer_id": { "type": "integer", "nullable": true }, "stage": { "type": "string", "nullable": true, "enum": [ "qualified", "proposal", "negotiation", "won", "lost" ] }, "probability": { "type": "integer", "nullable": true, "maximum": 100, "minimum": 0 }, "expected_value": { "type": "number", "format": "float", "nullable": true }, "currency_id": { "type": "integer", "nullable": true }, "expected_close_date": { "type": "string", "format": "date", "nullable": true }, "assigned_to": { "type": "integer", "nullable": true }, "quote_id": { "type": "integer", "nullable": true }, "description": { "type": "string", "nullable": true, "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Opportunity updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Opportunity" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Opportunities" ], "summary": "Delete opportunity", "description": "Soft-deletes an opportunity.", "operationId": "2101c52ad128679b7b53570636472d46", "parameters": [ { "name": "id", "in": "path", "description": "Opportunity ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Opportunity deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/opportunities/{id}/close": { "post": { "tags": [ "Opportunities" ], "summary": "Close opportunity", "description": "Closes an opportunity as won or lost.", "operationId": "4f748b68838846e0f521002584fc545b", "parameters": [ { "name": "id", "in": "path", "description": "Opportunity ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "stage" ], "properties": { "stage": { "type": "string", "example": "won", "enum": [ "won", "lost" ] }, "closed_reason": { "type": "string", "example": "Best price and feature set", "nullable": true, "maxLength": 2000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Opportunity closed", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Opportunity" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/opportunities/{id}/convert-to-quote": { "post": { "tags": [ "Opportunities" ], "summary": "Convert opportunity to quote", "description": "Marks an opportunity as ready for quoting.", "operationId": "f09e0f8981171370b180fbbb507bee02", "parameters": [ { "name": "id", "in": "path", "description": "Opportunity ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Opportunity moved to proposal stage", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Opportunity" } }, "type": "object" } } } }, "422": { "description": "Opportunity must be in negotiation or proposal stage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/overtime-requests": { "get": { "tags": [ "Overtime Requests" ], "summary": "List overtime requests", "description": "Returns a paginated list of overtime requests with optional filtering.", "operationId": "97f78b9d5d8ca98e02ae1a0ad5d76f38", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "employee_id", "in": "query", "description": "Filter by employee ID", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "paid" ] } }, { "name": "date_from", "in": "query", "description": "Filter from date (Y-m-d)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Filter to date (Y-m-d)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of overtime requests", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OvertimeRequest" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Overtime Requests" ], "summary": "Create overtime request", "description": "Creates a new overtime request. Status defaults to pending.", "operationId": "4382551dfca85add2144458c89236fc9", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "employee_id", "overtime_date", "overtime_hours" ], "properties": { "employee_id": { "type": "integer", "example": 1 }, "overtime_date": { "type": "string", "format": "date", "example": "2026-05-21" }, "overtime_hours": { "type": "number", "format": "float", "example": 2.5, "maximum": 12, "minimum": 0.5 }, "day_type": { "type": "string", "example": "regular", "nullable": true, "enum": [ "regular", "friday", "holiday" ] }, "notes": { "type": "string", "example": "Project deadline overtime", "nullable": true, "maxLength": 2000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Overtime request created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/OvertimeRequest" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/overtime-requests/{id}": { "get": { "tags": [ "Overtime Requests" ], "summary": "Get overtime request by ID", "description": "Returns a single overtime request record with employee details.", "operationId": "be3cb59ab59fb7b7b227be445a72ed14", "parameters": [ { "name": "id", "in": "path", "description": "Overtime request ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Overtime request details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/OvertimeRequest" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Overtime Requests" ], "summary": "Update overtime request", "description": "Updates a pending overtime request. Only allowed when status is pending.", "operationId": "37d90c90e36d8a608ff5d804bb540218", "parameters": [ { "name": "id", "in": "path", "description": "Overtime request ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "employee_id", "overtime_date", "overtime_hours" ], "properties": { "employee_id": { "type": "integer", "example": 1 }, "overtime_date": { "type": "string", "format": "date", "example": "2026-05-21" }, "overtime_hours": { "type": "number", "format": "float", "example": 3, "maximum": 12, "minimum": 0.5 }, "day_type": { "type": "string", "nullable": true, "enum": [ "regular", "friday", "holiday" ] }, "notes": { "type": "string", "nullable": true, "maxLength": 2000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Overtime request updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/OvertimeRequest" } }, "type": "object" } } } }, "422": { "description": "Cannot update non-pending request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Overtime Requests" ], "summary": "Delete overtime request", "description": "Deletes a pending overtime request. Only allowed when status is pending.", "operationId": "2c377ac7bbc130ee1df62cb968a38c35", "parameters": [ { "name": "id", "in": "path", "description": "Overtime request ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted successfully" }, "422": { "description": "Cannot delete non-pending request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/overtime-requests/{id}/approve": { "post": { "tags": [ "Overtime Requests" ], "summary": "Approve overtime request", "description": "Approves a pending overtime request, calculating the overtime amount per Saudi Labour Law Article 107.", "operationId": "d86ff2ad0632da7619f446cba87482ea", "parameters": [ { "name": "id", "in": "path", "description": "Overtime request ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Overtime request approved", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/OvertimeRequest" } }, "type": "object" } } } }, "422": { "description": "Cannot approve non-pending request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/overtime-requests/{id}/reject": { "post": { "tags": [ "Overtime Requests" ], "summary": "Reject overtime request", "description": "Rejects a pending overtime request with a mandatory reason.", "operationId": "3c1612a2502288d9ad80027ae9a87998", "parameters": [ { "name": "id", "in": "path", "description": "Overtime request ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reason" ], "properties": { "reason": { "type": "string", "example": "Budget constraints", "maxLength": 2000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Overtime request rejected", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/OvertimeRequest" } }, "type": "object" } } } }, "422": { "description": "Cannot reject non-pending request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/payment-allocations": { "get": { "tags": [ "Payment Allocations" ], "summary": "List payment allocations", "description": "Returns a paginated list of payment allocations. Filter by payment_id or allocatable.", "operationId": "e42a46e68c08d0ecaff7651cb6931d1d", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100 } }, { "name": "payment_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "allocatable_type", "in": "query", "description": "Fully-qualified model class name", "required": false, "schema": { "type": "string" } }, { "name": "allocatable_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "default": "allocation_date" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of payment allocations", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Payment Allocations" ], "summary": "Create payment allocation", "description": "Allocates a portion of a payment against an invoice or bill. Checks sufficient unallocated balance and reduces invoice amount_due.", "operationId": "c8e04e0cb1cebd5e3024fb3db147850a", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "payment_id", "allocatable_type", "allocatable_id", "amount" ], "properties": { "payment_id": { "type": "integer", "example": 10 }, "allocatable_type": { "description": "Fully-qualified model class", "type": "string", "example": "App\\Models\\Sales\\Invoice" }, "allocatable_id": { "type": "integer", "example": 42 }, "amount": { "type": "number", "format": "float", "example": 500 }, "allocation_date": { "type": "string", "format": "date", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Allocation created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Insufficient payment balance or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/payment-allocations/{id}": { "delete": { "tags": [ "Payment Allocations" ], "summary": "Reverse payment allocation", "description": "Deletes a payment allocation and restores the invoice amount_due and payment unallocated_amount.", "operationId": "791c0d6c8f2d79e8830c38e3839cf7ef", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Allocation reversed" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/payments": { "get": { "tags": [ "Payments" ], "summary": "List payments", "description": "Returns a paginated list of payments with optional filtering.", "operationId": "d42af22098bc46725c8075794e61e560", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Search by reference", "required": false, "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "Filter by payment type", "required": false, "schema": { "type": "string", "enum": [ "customer_payment", "vendor_payment" ] } }, { "name": "customer_id", "in": "query", "description": "Filter by customer ID", "required": false, "schema": { "type": "integer" } }, { "name": "vendor_id", "in": "query", "description": "Filter by vendor ID", "required": false, "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of payments", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Payments" ], "summary": "Create payment", "description": "Creates a new payment record.", "operationId": "480d4be6e6698ff0c959c6b44c4bacbc", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "type", "amount" ], "properties": { "type": { "type": "string", "example": "customer_payment", "enum": [ "customer_payment", "vendor_payment" ] }, "payment_date": { "type": "string", "format": "date", "example": "2024-01-15", "nullable": true }, "amount": { "type": "number", "format": "float", "example": 1150 }, "currency_code": { "type": "string", "example": "SAR", "nullable": true, "maxLength": 10 }, "exchange_rate": { "type": "number", "format": "float", "example": 1, "nullable": true }, "method": { "type": "string", "example": "bank_transfer", "nullable": true, "maxLength": 50 }, "customer_id": { "type": "integer", "example": 1, "nullable": true }, "vendor_id": { "type": "integer", "nullable": true }, "notes": { "type": "string", "nullable": true, "maxLength": 5000 }, "status": { "type": "string", "example": "draft", "nullable": true, "maxLength": 50 } }, "type": "object" } } } }, "responses": { "201": { "description": "Payment created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/Payment" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/payments/{id}": { "get": { "tags": [ "Payments" ], "summary": "Get payment by ID", "description": "Returns a single payment record.", "operationId": "1331884e82b60a4649bf370b22a043d7", "parameters": [ { "name": "id", "in": "path", "description": "Payment ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payment details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Payment" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Payments" ], "summary": "Update payment", "description": "Updates a draft payment record.", "operationId": "068985bb129c49d70a691e98414368bb", "parameters": [ { "name": "id", "in": "path", "description": "Payment ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "type", "amount" ], "properties": { "type": { "type": "string", "enum": [ "customer_payment", "vendor_payment" ] }, "payment_date": { "type": "string", "format": "date", "nullable": true }, "amount": { "type": "number", "format": "float" }, "currency_code": { "type": "string", "nullable": true, "maxLength": 10 }, "exchange_rate": { "type": "number", "format": "float", "nullable": true }, "method": { "type": "string", "nullable": true, "maxLength": 50 }, "customer_id": { "type": "integer", "nullable": true }, "vendor_id": { "type": "integer", "nullable": true }, "notes": { "type": "string", "nullable": true, "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Payment updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Payment" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/payments/{id}/post": { "post": { "tags": [ "Payments" ], "summary": "Post payment", "description": "Transitions a draft payment to posted status, locking it from further edits.", "operationId": "5d71c4d62346cebe7b762d4c8946178c", "parameters": [ { "name": "id", "in": "path", "description": "Payment ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payment posted", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Payment" } }, "type": "object" } } } }, "422": { "description": "Payment is not in draft status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/payroll-components": { "get": { "tags": [ "Payroll Components" ], "summary": "List payroll components", "description": "Returns a paginated list of payroll components with optional filtering.", "operationId": "54620cfd6620e0c1c20e7720c0292b3f", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "type", "in": "query", "description": "Filter by type", "required": false, "schema": { "type": "string", "enum": [ "earning", "deduction", "tax" ] } }, { "name": "is_active", "in": "query", "description": "Filter by active status", "required": false, "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "name" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "asc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of payroll components", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PayrollComponent" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Payroll Components" ], "summary": "Create payroll component", "description": "Creates a new payroll component (earning, deduction, or tax).", "operationId": "f44b277d84b7a37565a4765c58c03673", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "code", "type", "calculation" ], "properties": { "name": { "type": "string", "example": "Housing Allowance", "maxLength": 255 }, "code": { "type": "string", "example": "HOUSING", "maxLength": 20 }, "type": { "type": "string", "example": "earning", "enum": [ "earning", "deduction", "tax" ] }, "calculation": { "type": "string", "example": "percentage", "enum": [ "fixed", "percentage" ] }, "value": { "type": "number", "format": "float", "example": 25, "nullable": true }, "formula": { "description": "Custom formula expression", "type": "string", "nullable": true }, "is_taxable": { "type": "boolean", "example": false, "nullable": true }, "is_active": { "type": "boolean", "example": true, "nullable": true }, "account_id": { "description": "GL account ID", "type": "integer", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Payroll component created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/PayrollComponent" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/payroll-components/{id}": { "get": { "tags": [ "Payroll Components" ], "summary": "Get payroll component by ID", "description": "Returns a single payroll component.", "operationId": "ba255c376205591eef99b66c6a14860d", "parameters": [ { "name": "id", "in": "path", "description": "Payroll component ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payroll component details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/PayrollComponent" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Payroll Components" ], "summary": "Update payroll component", "description": "Updates an existing payroll component.", "operationId": "b18212463da31ce31a0174dd55116d81", "parameters": [ { "name": "id", "in": "path", "description": "Payroll component ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "code", "type", "calculation" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "code": { "type": "string", "maxLength": 20 }, "type": { "type": "string", "enum": [ "earning", "deduction", "tax" ] }, "calculation": { "type": "string", "enum": [ "fixed", "percentage" ] }, "value": { "type": "number", "format": "float", "nullable": true }, "formula": { "type": "string", "nullable": true }, "is_taxable": { "type": "boolean", "nullable": true }, "is_active": { "type": "boolean", "nullable": true }, "account_id": { "type": "integer", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Payroll component updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/PayrollComponent" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Payroll Components" ], "summary": "Delete payroll component", "description": "Deletes a payroll component. Returns an error if the component is used in active payrolls.", "operationId": "09497aaa28fa16e183c39034bb50ecb8", "parameters": [ { "name": "id", "in": "path", "description": "Payroll component ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted successfully" }, "422": { "description": "Component is used in active payrolls", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/payroll": { "get": { "tags": [ "Payroll" ], "summary": "List payroll records", "description": "Returns a paginated list of payroll runs with optional filtering.", "operationId": "5da454d677414e7e64ddc1a6e66c3018", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Search by reference", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "draft", "confirmed", "paid" ] } }, { "name": "month", "in": "query", "description": "Filter by month (1-12)", "required": false, "schema": { "type": "integer", "maximum": 12, "minimum": 1 } }, { "name": "year", "in": "query", "description": "Filter by year", "required": false, "schema": { "type": "integer", "example": 2024 } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of payroll records", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payroll" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Payroll" ], "summary": "Create payroll record", "description": "Creates a new payroll run for a given month and year.", "operationId": "7cf460209a4095a9d534d813d8bb93be", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "month", "year" ], "properties": { "reference": { "type": "string", "example": "PAY-2024-01", "nullable": true, "maxLength": 255 }, "month": { "type": "integer", "example": 1, "maximum": 12, "minimum": 1 }, "year": { "type": "integer", "example": 2024, "maximum": 2100, "minimum": 2000 }, "pay_date": { "type": "string", "format": "date", "example": "2024-01-31", "nullable": true }, "total_earnings": { "type": "number", "format": "float", "example": 50000, "nullable": true }, "total_deductions": { "type": "number", "format": "float", "example": 5000, "nullable": true }, "total_net": { "type": "number", "format": "float", "example": 45000, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Payroll record created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/Payroll" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/payroll/{id}": { "get": { "tags": [ "Payroll" ], "summary": "Get payroll record by ID", "description": "Returns a single payroll record.", "operationId": "042771296be46d96fe11df59f8f0310a", "parameters": [ { "name": "id", "in": "path", "description": "Payroll ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payroll record details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Payroll" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Payroll" ], "summary": "Update payroll record", "description": "Updates a draft payroll record.", "operationId": "a5fbb2fe97402f0583e0fbed1829acfc", "parameters": [ { "name": "id", "in": "path", "description": "Payroll ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "month", "year" ], "properties": { "reference": { "type": "string", "nullable": true, "maxLength": 255 }, "month": { "type": "integer", "maximum": 12, "minimum": 1 }, "year": { "type": "integer", "maximum": 2100, "minimum": 2000 }, "pay_date": { "type": "string", "format": "date", "nullable": true }, "total_earnings": { "type": "number", "format": "float", "nullable": true }, "total_deductions": { "type": "number", "format": "float", "nullable": true }, "total_net": { "type": "number", "format": "float", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Payroll record updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Payroll" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/payroll/{id}/confirm": { "post": { "tags": [ "Payroll" ], "summary": "Confirm payroll", "description": "Confirms a draft payroll run, locking the figures.", "operationId": "d700679f2a1a4afd8cb1aff186ec2604", "parameters": [ { "name": "id", "in": "path", "description": "Payroll ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payroll confirmed", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Payroll" } }, "type": "object" } } } }, "422": { "description": "Payroll is not in draft status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/payroll/{id}/post": { "post": { "tags": [ "Payroll" ], "summary": "Post payroll", "description": "Transitions a confirmed payroll to posted status.", "operationId": "53753f9154a8a90184392e7a459fe0a8", "parameters": [ { "name": "id", "in": "path", "description": "Payroll ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payroll posted", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Payroll" } }, "type": "object" } } } }, "422": { "description": "Payroll is not in confirmed status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/payroll/{id}/pay": { "post": { "tags": [ "Payroll" ], "summary": "Mark payroll as paid", "description": "Marks a posted payroll as paid and records the pay date.", "operationId": "14f72bbd53683b4c763f23d8b5cce79d", "parameters": [ { "name": "id", "in": "path", "description": "Payroll ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payroll paid", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Payroll" } }, "type": "object" } } } }, "422": { "description": "Payroll is not in posted status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/payroll/{id}/lines": { "get": { "tags": [ "Payroll" ], "summary": "Get payroll lines", "description": "Returns the individual employee pay lines for a payroll run.", "operationId": "150fd2419bc8b729696ef917297c6b03", "parameters": [ { "name": "id", "in": "path", "description": "Payroll ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payroll lines", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "employee_id": { "type": "integer", "example": 5 }, "employee_name": { "type": "string", "example": "John Doe" }, "basic_salary": { "type": "number", "format": "float", "example": 5000 }, "total_earnings": { "type": "number", "format": "float", "example": 5500 }, "total_deductions": { "type": "number", "format": "float", "example": 500 }, "net_pay": { "type": "number", "format": "float", "example": 5000 }, "components": { "type": "object", "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/physical-inventories": { "get": { "tags": [ "Physical Inventory" ], "summary": "List physical inventories", "description": "Returns a paginated list of physical inventories with optional filters.", "operationId": "eb6b006b0aea508976f55f3be33a009c", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string" } }, { "name": "warehouse_id", "in": "query", "description": "Filter by warehouse ID", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Paginated list of physical inventories" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Physical Inventory" ], "summary": "Create physical inventory", "operationId": "99f0105119a11f9424e9d436006d2444", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "warehouse_id", "count_date" ], "properties": { "warehouse_id": { "type": "integer" }, "count_date": { "type": "string", "format": "date" }, "notes": { "type": "string", "nullable": true, "maxLength": 1000 }, "inventory_account_id": { "type": "integer", "nullable": true }, "gain_account_id": { "type": "integer", "nullable": true }, "loss_account_id": { "type": "integer", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Physical inventory created" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/physical-inventories/{id}": { "get": { "tags": [ "Physical Inventory" ], "summary": "Get physical inventory by ID", "operationId": "4f8712f223635dc0a9b6f34f4818f2cb", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Physical inventory details" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Physical Inventory" ], "summary": "Update physical inventory", "description": "Updates a physical inventory. Only allowed when status is draft.", "operationId": "7cef5a4f7c925f2ab73d212fab4b69f8", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "warehouse_id", "count_date" ], "properties": { "warehouse_id": { "type": "integer" }, "count_date": { "type": "string", "format": "date" }, "notes": { "type": "string", "nullable": true, "maxLength": 1000 }, "inventory_account_id": { "type": "integer", "nullable": true }, "gain_account_id": { "type": "integer", "nullable": true }, "loss_account_id": { "type": "integer", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Physical inventory updated" }, "400": { "description": "Cannot update non-draft inventory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Physical Inventory" ], "summary": "Delete physical inventory", "description": "Soft-deletes a physical inventory. Only allowed when status is draft.", "operationId": "170c8e27a5c7d7e3a15f06d6ce0a18d8", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Physical inventory deleted" }, "400": { "description": "Cannot delete non-draft inventory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/physical-inventories/{id}/start": { "post": { "tags": [ "Physical Inventory" ], "summary": "Start physical inventory", "description": "Sets status to in_progress. Only allowed when status is draft.", "operationId": "0f0eb5e8f2459eaab0fc586fc2c89822", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Physical inventory started" }, "400": { "description": "Cannot start non-draft inventory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/physical-inventories/{id}/validate": { "post": { "tags": [ "Physical Inventory" ], "summary": "Validate physical inventory", "description": "Sets status to validated and records validated_at. Only allowed when status is in_progress.", "operationId": "139198a6eaaf3f47033dafd1b8e3d4f7", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Physical inventory validated" }, "400": { "description": "Cannot validate inventory not in_progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/physical-inventories/{id}/lines": { "get": { "tags": [ "Physical Inventory" ], "summary": "Get physical inventory lines", "description": "Returns all count lines for the given physical inventory, including product and location details.", "operationId": "903e8d3ef9ab3da669c8898c76f18ba9", "parameters": [ { "name": "id", "in": "path", "description": "Physical Inventory ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Physical inventory lines", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "product_id": { "type": "integer", "example": 3 }, "product_name": { "type": "string", "example": "Office Chair", "nullable": true }, "location_id": { "type": "integer", "example": 2, "nullable": true }, "location_name": { "type": "string", "example": "Shelf A1", "nullable": true }, "system_qty": { "type": "number", "format": "float", "example": 10 }, "counted_qty": { "type": "number", "format": "float", "example": 9 }, "difference_qty": { "type": "number", "format": "float", "example": -1 }, "unit_cost": { "type": "number", "format": "float", "example": 250 }, "difference_value": { "type": "number", "format": "float", "example": -250 }, "notes": { "type": "string", "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Physical Inventory" ], "summary": "Update physical inventory lines", "description": "Updates counted quantities for lines on an in_progress physical inventory. Recalculates difference columns automatically.", "operationId": "760d39e50fb507531cb8e3ef0e0b2956", "parameters": [ { "name": "id", "in": "path", "description": "Physical Inventory ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "lines" ], "properties": { "lines": { "type": "array", "items": { "required": [ "id", "counted_qty" ], "properties": { "id": { "description": "Line ID", "type": "integer", "example": 1 }, "counted_qty": { "type": "number", "format": "float", "example": 9, "minimum": 0 } }, "type": "object" }, "minItems": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Lines updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "properties": { "updated": { "type": "integer", "example": 3 } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Physical inventory is not in_progress or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/product-categories": { "get": { "tags": [ "Product Categories" ], "summary": "List product categories", "description": "Returns a paginated list of product categories with optional name search.", "operationId": "11b5248eef36c824cdba8b0efd260087", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "search", "in": "query", "description": "Search by name", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of product categories" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Product Categories" ], "summary": "Create product category", "operationId": "a2aaf272a2ace93a64612ab8ff1f3520", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "parent_id": { "type": "integer", "nullable": true }, "slug": { "type": "string", "nullable": true, "maxLength": 255 } }, "type": "object" } } } }, "responses": { "201": { "description": "Product category created" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/product-categories/{id}": { "get": { "tags": [ "Product Categories" ], "summary": "Get product category by ID", "operationId": "6e9a10fad2ea7656c5753b02667a400e", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Product category details" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Product Categories" ], "summary": "Update product category", "operationId": "2fdda971769e969185381f11935e4703", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "parent_id": { "type": "integer", "nullable": true }, "slug": { "type": "string", "nullable": true, "maxLength": 255 } }, "type": "object" } } } }, "responses": { "200": { "description": "Product category updated" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Product Categories" ], "summary": "Delete product category", "operationId": "f2ccc5c6fe3c32ff00593e88e4c5cd18", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Product category deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/products": { "get": { "tags": [ "Products" ], "summary": "List products", "description": "Returns a paginated list of products with optional search and filtering.", "operationId": "c821c7f9e41e08594ad4eae5a99e812e", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Search by name or SKU", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of products", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Products" ], "summary": "Create product", "description": "Creates a new product in the catalogue.", "operationId": "a59d7d76c37cb085c473698dba983938", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Laptop Pro", "maxLength": 255 }, "sku": { "type": "string", "example": "LAP-001", "nullable": true, "maxLength": 100 }, "barcode": { "type": "string", "nullable": true, "maxLength": 100 }, "description": { "type": "string", "nullable": true, "maxLength": 5000 }, "category_id": { "type": "integer", "example": 1, "nullable": true }, "unit": { "type": "string", "example": "pcs", "nullable": true, "maxLength": 50 }, "type": { "type": "string", "example": "storable", "nullable": true, "maxLength": 50, "enum": [ "storable", "consumable", "service" ] }, "sale_price": { "type": "number", "format": "float", "example": 2500, "nullable": true }, "purchase_price": { "type": "number", "format": "float", "example": 1900, "nullable": true }, "cost_price": { "type": "number", "format": "float", "example": 1800, "nullable": true }, "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": "Created" }, "data": { "$ref": "#/components/schemas/Product" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/products/{id}": { "get": { "tags": [ "Products" ], "summary": "Get product by ID", "description": "Returns a single product record.", "operationId": "900da7e5cb549dc28cfd19d90d1f6710", "parameters": [ { "name": "id", "in": "path", "description": "Product ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Product details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Product" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Products" ], "summary": "Update product", "description": "Updates an existing product record.", "operationId": "1ab61d88b4cfff271ad6afe7d8cf0388", "parameters": [ { "name": "id", "in": "path", "description": "Product ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Laptop Pro", "maxLength": 255 }, "sku": { "type": "string", "nullable": true, "maxLength": 100 }, "barcode": { "type": "string", "nullable": true, "maxLength": 100 }, "description": { "type": "string", "nullable": true, "maxLength": 5000 }, "category_id": { "type": "integer", "nullable": true }, "unit": { "type": "string", "nullable": true, "maxLength": 50 }, "type": { "type": "string", "nullable": true, "maxLength": 50 }, "sale_price": { "type": "number", "format": "float", "nullable": true }, "purchase_price": { "type": "number", "format": "float", "nullable": true }, "cost_price": { "type": "number", "format": "float", "nullable": true }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Product updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Product" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Products" ], "summary": "Delete product", "description": "Soft-deletes a product record.", "operationId": "9dcbacba304004f42c516998d50fe6fa", "parameters": [ { "name": "id", "in": "path", "description": "Product ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Product deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/projects": { "get": { "tags": [ "Projects" ], "summary": "List projects", "description": "Returns a paginated list of projects with optional filtering.", "operationId": "d8bc32b45579a2263ca77907248c9002", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Search by project name", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "planning", "active", "on_hold", "completed", "cancelled" ] } }, { "name": "customer_id", "in": "query", "description": "Filter by customer ID", "required": false, "schema": { "type": "integer" } }, { "name": "manager_id", "in": "query", "description": "Filter by manager ID", "required": false, "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of projects", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Projects" ], "summary": "Create project", "description": "Creates a new project.", "operationId": "d14ce90da851ad8044ec318a766df32e", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "start_date" ], "properties": { "name": { "type": "string", "example": "Website Redesign", "maxLength": 255 }, "customer_id": { "type": "integer", "example": 1, "nullable": true }, "manager_id": { "type": "integer", "example": 2, "nullable": true }, "status": { "type": "string", "example": "planning", "nullable": true, "enum": [ "planning", "active", "on_hold", "completed", "cancelled" ] }, "start_date": { "type": "string", "format": "date", "example": "2026-01-01" }, "end_date": { "type": "string", "format": "date", "example": "2026-06-30", "nullable": true }, "budget": { "type": "number", "format": "float", "example": 50000, "nullable": true }, "currency_id": { "type": "integer", "example": 1, "nullable": true }, "description": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Project created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/Project" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/projects/{id}": { "get": { "tags": [ "Projects" ], "summary": "Get project by ID", "description": "Returns a single project with customer, manager, milestones, task counts, and time summary.", "operationId": "83c87bebdc302e4ae4afcefcf319d08c", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Project details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Project" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Projects" ], "summary": "Update project", "description": "Updates an existing project (not allowed if cancelled).", "operationId": "62d247065d872bb3694822fd1a77b76e", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "start_date" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "customer_id": { "type": "integer", "nullable": true }, "manager_id": { "type": "integer", "nullable": true }, "status": { "type": "string", "nullable": true, "enum": [ "planning", "active", "on_hold", "completed", "cancelled" ] }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date", "nullable": true }, "budget": { "type": "number", "format": "float", "nullable": true }, "currency_id": { "type": "integer", "nullable": true }, "description": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Project updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Project" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Projects" ], "summary": "Delete project", "description": "Soft-deletes a project. Only allowed if there are no tasks or time entries.", "operationId": "0e1ef9693d0bf640ec8a8027909a5902", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Project deleted" }, "422": { "description": "Project has tasks or time entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/projects/{id}/activate": { "post": { "tags": [ "Projects" ], "summary": "Activate project", "description": "Transitions a project from planning or on_hold to active.", "operationId": "531d2f9bbc8e392d256d8a0753248e81", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Project activated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Project" } }, "type": "object" } } } }, "422": { "description": "Invalid status transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/projects/{id}/complete": { "post": { "tags": [ "Projects" ], "summary": "Complete project", "description": "Marks a project as completed.", "operationId": "0c921d6eb6ef4d9bea017e52604645a4", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "override": { "description": "Force complete even if tasks are not done", "type": "boolean", "example": false } }, "type": "object" } } } }, "responses": { "200": { "description": "Project completed", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Project" } }, "type": "object" } } } }, "422": { "description": "Pending tasks exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/projects/{id}/cancel": { "post": { "tags": [ "Projects" ], "summary": "Cancel project", "description": "Cancels a project.", "operationId": "c88fd27e8e98d3c901e7a501403bc847", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Project cancelled", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Project" } }, "type": "object" } } } }, "422": { "description": "Project already cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/projects/{id}/invoice": { "post": { "tags": [ "Projects" ], "summary": "Generate invoice from time entries", "description": "Creates a draft invoice from billable, unbilled time entries for the project.", "operationId": "eed5c6b0c16027422f6b061b21ae52a1", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "time_entry_ids": { "description": "Specific time entry IDs to invoice. If omitted, all unbilled billable entries are used.", "type": "array", "items": { "type": "integer" }, "nullable": true }, "hourly_rate": { "description": "Override hourly rate", "type": "number", "format": "float", "example": 150, "nullable": true }, "invoice_date": { "type": "string", "format": "date", "example": "2026-05-21", "nullable": true }, "due_date": { "type": "string", "format": "date", "example": "2026-06-20", "nullable": true }, "description": { "description": "Line item description template", "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Invoice created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/Invoice" } }, "type": "object" } } } }, "422": { "description": "No unbilled time entries found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/projects/{projectId}/milestones": { "get": { "tags": [ "Project Milestones" ], "summary": "List project milestones", "description": "Returns all milestones for a given project, sorted by due date.", "operationId": "c85561730c2ff6de47e255c61f1bbbfe", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of milestones", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectMilestone" } } }, "type": "object" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Project Milestones" ], "summary": "Create milestone", "description": "Creates a new milestone for the project.", "operationId": "7c4b0bff4140a8d1dd9be17a2574e560", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "due_date" ], "properties": { "name": { "type": "string", "example": "Phase 1 Complete" }, "due_date": { "type": "string", "format": "date", "example": "2026-03-31" }, "notes": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Milestone created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/ProjectMilestone" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/projects/{projectId}/milestones/{milestoneId}": { "get": { "tags": [ "Project Milestones" ], "summary": "Get milestone", "description": "Returns a single milestone.", "operationId": "492f91af283e85f7141a61827db79f57", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } }, { "name": "milestoneId", "in": "path", "description": "Milestone ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Milestone details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ProjectMilestone" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Project Milestones" ], "summary": "Update milestone", "description": "Updates a milestone. Not allowed if already completed.", "operationId": "bbe187fca8d42542bb0ac7864a7086b4", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } }, { "name": "milestoneId", "in": "path", "description": "Milestone ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "due_date" ], "properties": { "name": { "type": "string" }, "due_date": { "type": "string", "format": "date" }, "notes": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Milestone updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ProjectMilestone" } }, "type": "object" } } } }, "422": { "description": "Milestone already completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Project Milestones" ], "summary": "Delete milestone", "description": "Deletes a milestone. Not allowed if already completed.", "operationId": "2be12c3a25a633e189c14f0890260a18", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } }, { "name": "milestoneId", "in": "path", "description": "Milestone ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Milestone deleted" }, "422": { "description": "Milestone already completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/projects/{projectId}/milestones/{milestoneId}/complete": { "post": { "tags": [ "Project Milestones" ], "summary": "Complete milestone", "description": "Marks a milestone as completed by setting completed_at to now.", "operationId": "1d6e5af28bbb81f770901b994bc5b862", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } }, { "name": "milestoneId", "in": "path", "description": "Milestone ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Milestone completed", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ProjectMilestone" } }, "type": "object" } } } }, "422": { "description": "Milestone already completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/projects/{projectId}/tasks": { "get": { "tags": [ "Project Tasks" ], "summary": "List project tasks", "description": "Returns paginated tasks for a project with optional filters.", "operationId": "ca86ff1ed3913a368015d097180c0109", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "todo", "in_progress", "review", "done" ] } }, { "name": "priority", "in": "query", "description": "Filter by priority", "required": false, "schema": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] } }, { "name": "assigned_to", "in": "query", "description": "Filter by assigned user ID", "required": false, "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of tasks", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectTask" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Project Tasks" ], "summary": "Create task", "description": "Creates a new task for the project.", "operationId": "03e6028632efea6e45e47b73945e674c", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title" ], "properties": { "title": { "type": "string", "example": "Design homepage mockup", "maxLength": 255 }, "description": { "type": "string", "nullable": true }, "assigned_to": { "type": "integer", "nullable": true }, "status": { "type": "string", "example": "todo", "nullable": true, "enum": [ "todo", "in_progress", "review", "done" ] }, "priority": { "type": "string", "example": "medium", "nullable": true, "enum": [ "low", "medium", "high", "urgent" ] }, "due_date": { "type": "string", "format": "date", "nullable": true }, "estimated_hours": { "type": "number", "format": "float", "example": 8, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Task created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/ProjectTask" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/projects/{projectId}/tasks/{taskId}": { "get": { "tags": [ "Project Tasks" ], "summary": "Get task", "description": "Returns a single task with assignee and time entry summary.", "operationId": "dbe473f279310d0c3bdc47cfbad94f26", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } }, { "name": "taskId", "in": "path", "description": "Task ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Task details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ProjectTask" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Project Tasks" ], "summary": "Update task", "description": "Updates a task.", "operationId": "16d214960474610977628c731f9348e8", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } }, { "name": "taskId", "in": "path", "description": "Task ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title" ], "properties": { "title": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "nullable": true }, "assigned_to": { "type": "integer", "nullable": true }, "status": { "type": "string", "nullable": true, "enum": [ "todo", "in_progress", "review", "done" ] }, "priority": { "type": "string", "nullable": true, "enum": [ "low", "medium", "high", "urgent" ] }, "due_date": { "type": "string", "format": "date", "nullable": true }, "estimated_hours": { "type": "number", "format": "float", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Task updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ProjectTask" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Project Tasks" ], "summary": "Delete task", "description": "Soft-deletes a task. Only allowed if status is todo.", "operationId": "757d5e521a37d952a3964d0e3bcf0e98", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } }, { "name": "taskId", "in": "path", "description": "Task ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Task deleted" }, "422": { "description": "Task is not in todo status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/projects/{projectId}/tasks/{taskId}/status": { "patch": { "tags": [ "Project Tasks" ], "summary": "Update task status", "description": "Updates the status of a task with transition validation.", "operationId": "467d4c086e5f212f849e28ae37f94bfc", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } }, { "name": "taskId", "in": "path", "description": "Task ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "todo", "in_progress", "review", "done" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Task status updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ProjectTask" } }, "type": "object" } } } }, "422": { "description": "Invalid status transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/projects/{projectId}/tasks/{taskId}/assign": { "patch": { "tags": [ "Project Tasks" ], "summary": "Assign task", "description": "Assigns a task to a user.", "operationId": "347595a2b118acf7dc5a4a50782798ae", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } }, { "name": "taskId", "in": "path", "description": "Task ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "user_id" ], "properties": { "user_id": { "type": "integer", "example": 3 } }, "type": "object" } } } }, "responses": { "200": { "description": "Task assigned", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ProjectTask" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/projects/{projectId}/time-entries": { "get": { "tags": [ "Project Time Entries" ], "summary": "List time entries for project", "description": "Returns paginated time entries for a project with optional filters and summary totals.", "operationId": "a93146e66e2c00230fd17c122dd4755b", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "user_id", "in": "query", "description": "Filter by user ID", "required": false, "schema": { "type": "integer" } }, { "name": "task_id", "in": "query", "description": "Filter by task ID", "required": false, "schema": { "type": "integer" } }, { "name": "billable", "in": "query", "description": "Filter billable entries", "required": false, "schema": { "type": "boolean" } }, { "name": "billed", "in": "query", "description": "Filter billed entries", "required": false, "schema": { "type": "boolean" } }, { "name": "date_from", "in": "query", "description": "Date range start", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Date range end", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "date" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated time entries with summary", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectTimeEntry" } }, "meta": { "properties": { "total_hours": { "type": "number", "format": "float" }, "billable_hours": { "type": "number", "format": "float" }, "unbilled_hours": { "type": "number", "format": "float" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Project Time Entries" ], "summary": "Log time entry", "description": "Creates a new time entry for the project.", "operationId": "a6f7cc78c6b5c72aec4979d0c6656350", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "user_id", "hours", "date" ], "properties": { "task_id": { "type": "integer", "nullable": true }, "user_id": { "type": "integer", "example": 1 }, "description": { "type": "string", "nullable": true }, "hours": { "type": "number", "format": "float", "example": 3.5, "maximum": 24, "minimum": 0.1 }, "date": { "type": "string", "format": "date", "example": "2026-05-21" }, "billable": { "type": "boolean", "example": true }, "billed": { "type": "boolean", "example": false } }, "type": "object" } } } }, "responses": { "201": { "description": "Time entry created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/ProjectTimeEntry" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/time-entries": { "get": { "tags": [ "Project Time Entries" ], "summary": "List all time entries (cross-project)", "description": "Returns paginated time entries across all projects for the company.", "operationId": "ba7bbd21c3e3b5df68d41717e255516b", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "project_id", "in": "query", "description": "Filter by project", "required": false, "schema": { "type": "integer" } }, { "name": "user_id", "in": "query", "description": "Filter by user", "required": false, "schema": { "type": "integer" } }, { "name": "billable", "in": "query", "description": "Filter billable", "required": false, "schema": { "type": "boolean" } }, { "name": "billed", "in": "query", "description": "Filter billed", "required": false, "schema": { "type": "boolean" } }, { "name": "date_from", "in": "query", "description": "Date range start", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Date range end", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Paginated time entries", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectTimeEntry" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/projects/{projectId}/time-entries/{entryId}": { "get": { "tags": [ "Project Time Entries" ], "summary": "Get time entry", "description": "Returns a single time entry.", "operationId": "ab1599bd7ae975e22b1438d876b13173", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } }, { "name": "entryId", "in": "path", "description": "Time Entry ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Time entry details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ProjectTimeEntry" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Project Time Entries" ], "summary": "Update time entry", "description": "Updates a time entry. Not allowed if already billed.", "operationId": "958f4884c0e638dbd9697bc2865b6f8d", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } }, { "name": "entryId", "in": "path", "description": "Time Entry ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "user_id", "hours", "date" ], "properties": { "task_id": { "type": "integer", "nullable": true }, "user_id": { "type": "integer" }, "description": { "type": "string", "nullable": true }, "hours": { "type": "number", "format": "float", "maximum": 24, "minimum": 0.1 }, "date": { "type": "string", "format": "date" }, "billable": { "type": "boolean" }, "billed": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Time entry updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ProjectTimeEntry" } }, "type": "object" } } } }, "422": { "description": "Billed entries cannot be edited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Project Time Entries" ], "summary": "Delete time entry", "description": "Soft-deletes a time entry. Not allowed if already billed.", "operationId": "5a95da3493092b2bdf8e05d90b09a655", "parameters": [ { "name": "projectId", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } }, { "name": "entryId", "in": "path", "description": "Time Entry ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Time entry deleted" }, "422": { "description": "Billed entries cannot be deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/purchase-orders": { "get": { "tags": [ "Purchase Orders" ], "summary": "List purchase orders", "description": "Returns a paginated list of purchase orders with optional search and filtering.", "operationId": "d0af9ee2243bdc81323a6295f4e01ee8", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Search by reference or vendor name", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "draft", "submitted", "approved", "received", "cancelled" ] } }, { "name": "vendor_id", "in": "query", "description": "Filter by vendor ID", "required": false, "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of purchase orders", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseOrder" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Purchase Orders" ], "summary": "Create purchase order", "description": "Creates a new purchase order.", "operationId": "6dc44c32b3476c7c23358234f0bd0a78", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "vendor_id" ], "properties": { "vendor_id": { "type": "integer", "example": 1 }, "requisition_id": { "type": "integer", "nullable": true }, "currency_id": { "type": "integer", "example": 1, "nullable": true }, "exchange_rate": { "type": "number", "format": "float", "example": 1, "nullable": true }, "order_date": { "type": "string", "format": "date", "example": "2024-01-15", "nullable": true }, "expected_delivery_date": { "type": "string", "format": "date", "example": "2024-02-15", "nullable": true }, "subtotal": { "type": "number", "format": "float", "example": 2000, "nullable": true }, "tax_amount": { "type": "number", "format": "float", "example": 300, "nullable": true }, "landed_cost": { "type": "number", "format": "float", "example": 0, "nullable": true }, "total": { "type": "number", "format": "float", "example": 2300, "nullable": true }, "warehouse_id": { "type": "integer", "example": 1, "nullable": true }, "notes": { "type": "string", "nullable": true, "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Purchase order created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/PurchaseOrder" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/purchase-orders/{id}": { "get": { "tags": [ "Purchase Orders" ], "summary": "Get purchase order by ID", "description": "Returns a single purchase order with line items.", "operationId": "1b6c934d4b1bf13a1055947df189df4e", "parameters": [ { "name": "id", "in": "path", "description": "Purchase order ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Purchase order details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/PurchaseOrder" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Purchase Orders" ], "summary": "Update purchase order", "description": "Updates a draft purchase order.", "operationId": "c94bc92996231519eaa8fe43d63eb567", "parameters": [ { "name": "id", "in": "path", "description": "Purchase order ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "vendor_id" ], "properties": { "vendor_id": { "type": "integer", "example": 1 }, "currency_id": { "type": "integer", "nullable": true }, "exchange_rate": { "type": "number", "format": "float", "nullable": true }, "order_date": { "type": "string", "format": "date", "nullable": true }, "expected_delivery_date": { "type": "string", "format": "date", "nullable": true }, "subtotal": { "type": "number", "format": "float", "nullable": true }, "tax_amount": { "type": "number", "format": "float", "nullable": true }, "landed_cost": { "type": "number", "format": "float", "nullable": true }, "total": { "type": "number", "format": "float", "nullable": true }, "warehouse_id": { "type": "integer", "nullable": true }, "notes": { "type": "string", "nullable": true, "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Purchase order updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/PurchaseOrder" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Purchase Orders" ], "summary": "Delete purchase order", "description": "Soft-deletes a purchase order.", "operationId": "980cf07c180c2c6c9d348be4b22efed0", "parameters": [ { "name": "id", "in": "path", "description": "Purchase order ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Purchase order deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/purchase-orders/{id}/submit": { "post": { "tags": [ "Purchase Orders" ], "summary": "Submit purchase order for approval", "description": "Transitions a draft purchase order to submitted status.", "operationId": "bdcef9e982995122fabf546fed221539", "parameters": [ { "name": "id", "in": "path", "description": "Purchase order ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Purchase order submitted", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/PurchaseOrder" } }, "type": "object" } } } }, "422": { "description": "Order is not in draft status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/purchase-orders/{id}/pdf": { "get": { "tags": [ "Purchase Orders" ], "summary": "Get purchase order PDF URL", "description": "Returns the download URL for the purchase order PDF.", "operationId": "929728f481587f792d6c678b244e6b17", "parameters": [ { "name": "id", "in": "path", "description": "Purchase order ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "PDF download URL", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "properties": { "url": { "type": "string", "format": "uri", "example": "https://app.example.com/pdf/purchase-orders/1" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/purchase-orders/{id}/confirm": { "post": { "tags": [ "Purchase Orders" ], "summary": "Confirm purchase order", "description": "Approves a submitted purchase order.", "operationId": "ce00f9bbb3f58dac31019e16f9d15b66", "parameters": [ { "name": "id", "in": "path", "description": "Purchase order ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Purchase order confirmed", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/PurchaseOrder" } }, "type": "object" } } } }, "422": { "description": "Order is not in submitted status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/purchase-orders/{id}/cancel": { "post": { "tags": [ "Purchase Orders" ], "summary": "Cancel purchase order", "description": "Cancels a purchase order that has not been received or already cancelled.", "operationId": "4b0a387f1b14cf89781170b06c293092", "parameters": [ { "name": "id", "in": "path", "description": "Purchase order ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "cancellation_reason": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Purchase order cancelled", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/PurchaseOrder" } }, "type": "object" } } } }, "422": { "description": "Purchase order cannot be cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/purchase-orders/{id}/lines": { "get": { "tags": [ "Purchase Orders" ], "summary": "List purchase order lines", "description": "Returns all line items for a purchase order.", "operationId": "d42f116b7a350ebd4d49b133838c014d", "parameters": [ { "name": "id", "in": "path", "description": "Purchase order ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of purchase order lines", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/purchase-orders/{id}/convert-to-bill": { "post": { "tags": [ "Purchase Orders" ], "summary": "Convert purchase order to vendor bill", "description": "Creates a vendor bill from a confirmed purchase order. Copies all line items.", "operationId": "a6f17f818dae61012e7175d2922fcc85", "parameters": [ { "name": "id", "in": "path", "description": "Purchase order ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Vendor bill created from purchase order", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Bill" } }, "type": "object" } } } }, "422": { "description": "PO must be confirmed or duplicate bill exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/quotes": { "get": { "tags": [ "Quotes" ], "summary": "List quotes", "description": "Returns a paginated list of quotations with optional filtering.", "operationId": "55896c82efc995d4e46d0d7189483129", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Search by reference or customer name", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "draft", "sent", "accepted", "rejected", "expired" ] } }, { "name": "customer_id", "in": "query", "description": "Filter by customer ID", "required": false, "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of quotes", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Quote" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Quotes" ], "summary": "Create quote", "description": "Creates a new quotation for a customer.", "operationId": "e1605ec2ea6bebddbc6c83783c3ed5a6", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "customer_id" ], "properties": { "customer_id": { "type": "integer", "example": 1 }, "currency_id": { "type": "integer", "example": 1, "nullable": true }, "exchange_rate": { "type": "number", "format": "float", "example": 1, "nullable": true }, "quote_date": { "type": "string", "format": "date", "example": "2024-01-15", "nullable": true }, "expiry_date": { "type": "string", "format": "date", "example": "2024-02-15", "nullable": true }, "subtotal": { "type": "number", "format": "float", "example": 1000, "nullable": true }, "discount_amount": { "type": "number", "format": "float", "example": 0, "nullable": true }, "tax_amount": { "type": "number", "format": "float", "example": 150, "nullable": true }, "total": { "type": "number", "format": "float", "example": 1150, "nullable": true }, "notes": { "type": "string", "nullable": true, "maxLength": 5000 }, "terms": { "type": "string", "nullable": true, "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Quote created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/Quote" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/quotes/{id}": { "get": { "tags": [ "Quotes" ], "summary": "Get quote by ID", "description": "Returns a single quote with line items.", "operationId": "451bbe89f2be1f8ddfa73d76dbb0f227", "parameters": [ { "name": "id", "in": "path", "description": "Quote ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Quote details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Quote" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Quotes" ], "summary": "Update quote", "description": "Updates a draft quote.", "operationId": "a308c86572f538405c2da9a796ab1a59", "parameters": [ { "name": "id", "in": "path", "description": "Quote ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "customer_id" ], "properties": { "customer_id": { "type": "integer" }, "currency_id": { "type": "integer", "nullable": true }, "exchange_rate": { "type": "number", "format": "float", "nullable": true }, "quote_date": { "type": "string", "format": "date", "nullable": true }, "expiry_date": { "type": "string", "format": "date", "nullable": true }, "subtotal": { "type": "number", "format": "float", "nullable": true }, "discount_amount": { "type": "number", "format": "float", "nullable": true }, "tax_amount": { "type": "number", "format": "float", "nullable": true }, "total": { "type": "number", "format": "float", "nullable": true }, "notes": { "type": "string", "nullable": true, "maxLength": 5000 }, "terms": { "type": "string", "nullable": true, "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Quote updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Quote" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Quotes" ], "summary": "Delete quote", "description": "Soft-deletes a quote.", "operationId": "e0083f49ae2de0d7945c879c337475b6", "parameters": [ { "name": "id", "in": "path", "description": "Quote ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Quote deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/quotes/{id}/convert-to-order": { "post": { "tags": [ "Quotes" ], "summary": "Convert quote to sales order", "description": "Converts an accepted quote into a sales order. Copies all line items from the quote.", "operationId": "eebf519f999b855009d71ed5a4872384", "parameters": [ { "name": "id", "in": "path", "description": "Quote ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Sales order created from quote", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/SalesOrder" } }, "type": "object" } } } }, "422": { "description": "Quote must be in accepted status or duplicate order exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/quotes/{id}/send": { "post": { "tags": [ "Quotes" ], "summary": "Send quote to customer", "description": "Marks a draft quote as sent.", "operationId": "371a208261ced77aafe1072ed796b3e8", "parameters": [ { "name": "id", "in": "path", "description": "Quote ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Quote marked as sent", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Quote" } }, "type": "object" } } } }, "422": { "description": "Quote has already been sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/quotes/{id}/accept": { "post": { "tags": [ "Quotes" ], "summary": "Accept quote", "description": "Marks a sent quote as accepted by the customer.", "operationId": "083497648db9203dcf9b4251b9453663", "parameters": [ { "name": "id", "in": "path", "description": "Quote ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Quote accepted", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Quote" } }, "type": "object" } } } }, "422": { "description": "Quote is not in sent status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/quotes/{id}/reject": { "post": { "tags": [ "Quotes" ], "summary": "Reject quote", "description": "Marks a sent or draft quote as rejected.", "operationId": "dd08aa23220fbb9187507d3944a8ce34", "parameters": [ { "name": "id", "in": "path", "description": "Quote ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "rejection_reason": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Quote rejected", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Quote" } }, "type": "object" } } } }, "422": { "description": "Quote cannot be rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/quotes/{id}/lines": { "get": { "tags": [ "Quotes" ], "summary": "List quote lines", "description": "Returns all line items for a quote.", "operationId": "127f3d1aaaff93615b7de796621defea", "parameters": [ { "name": "id", "in": "path", "description": "Quote ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of quote lines", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/recurring-journal-entries": { "get": { "tags": [ "Recurring Journal Entries" ], "summary": "List recurring journal entries", "description": "Returns a paginated list of recurring journal entries with optional filtering.", "operationId": "218d1d0076f144f85bff475675b9ee82", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "is_active", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "frequency", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "monthly", "quarterly", "semi_annual", "annual" ] } } ], "responses": { "200": { "description": "Paginated list of recurring journal entries" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Recurring Journal Entries" ], "summary": "Create recurring journal entry", "operationId": "3b340da50d1b9c11d5e52da8d52b14de", "responses": { "201": { "description": "Recurring journal entry created" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/recurring-journal-entries/{id}": { "get": { "tags": [ "Recurring Journal Entries" ], "summary": "Get recurring journal entry by ID", "operationId": "b949bcc5b20d4d097f16bf0e84135a17", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Recurring journal entry details" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Recurring Journal Entries" ], "summary": "Update recurring journal entry", "operationId": "fe317dab92f5177c9fa7e9c32d907603", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Recurring journal entry updated" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Recurring Journal Entries" ], "summary": "Delete recurring journal entry", "operationId": "173866fde6381ce7bbca59d2ddc58d0a", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/recurring-journal-entries/{id}/run": { "post": { "tags": [ "Recurring Journal Entries" ], "summary": "Run a recurring journal entry", "description": "Advances the next run date and updates last_run_date. Entry must be active.", "operationId": "a543e279601d99c7523972a70d68c116", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Entry run successfully" }, "422": { "description": "Entry is not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/recurring-journal-entries/{id}/activate": { "post": { "tags": [ "Recurring Journal Entries" ], "summary": "Activate a recurring journal entry", "operationId": "a8bbd20268f7bb147f8c9f82b76c6658", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Entry activated" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/recurring-journal-entries/{id}/pause": { "post": { "tags": [ "Recurring Journal Entries" ], "summary": "Pause a recurring journal entry", "operationId": "cc4e66e7d40a13db74c09422c588ea31", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Entry paused" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/reports/sales": { "get": { "tags": [ "Reports" ], "summary": "Sales report", "description": "Returns aggregated sales metrics for a given period.", "operationId": "9b83e44d9295f4a7eb4f71015984e980", "parameters": [ { "name": "from", "in": "query", "description": "Start date (defaults to start of current month)", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-01-01" } }, { "name": "to", "in": "query", "description": "End date (defaults to end of current month)", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-01-31" } } ], "responses": { "200": { "description": "Sales report data", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "properties": { "period": { "properties": { "from": { "type": "string", "format": "date", "example": "2024-01-01" }, "to": { "type": "string", "format": "date", "example": "2024-01-31" } }, "type": "object" }, "revenue": { "description": "Total invoice revenue", "type": "number", "format": "float", "example": 150000 }, "outstanding": { "description": "Total outstanding receivables", "type": "number", "format": "float", "example": 45000 }, "invoice_count": { "description": "Number of invoices", "type": "integer", "example": 23 }, "order_value": { "description": "Total sales order value", "type": "number", "format": "float", "example": 180000 }, "order_count": { "description": "Number of sales orders", "type": "integer", "example": 30 } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Invalid date range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/reports/purchases": { "get": { "tags": [ "Reports" ], "summary": "Purchases report", "description": "Returns aggregated purchasing metrics for a given period.", "operationId": "5de3af793e3c8b44c8092d462e7b0d45", "parameters": [ { "name": "from", "in": "query", "description": "Start date (defaults to start of current month)", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-01-01" } }, { "name": "to", "in": "query", "description": "End date (defaults to end of current month)", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-01-31" } } ], "responses": { "200": { "description": "Purchases report data", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "properties": { "period": { "properties": { "from": { "type": "string", "format": "date", "example": "2024-01-01" }, "to": { "type": "string", "format": "date", "example": "2024-01-31" } }, "type": "object" }, "total_expense": { "description": "Total bill expense", "type": "number", "format": "float", "example": 80000 }, "unpaid": { "description": "Total unpaid payables", "type": "number", "format": "float", "example": 25000 }, "bill_count": { "description": "Number of bills", "type": "integer", "example": 15 }, "order_value": { "description": "Total purchase order value", "type": "number", "format": "float", "example": 95000 }, "order_count": { "description": "Number of purchase orders", "type": "integer", "example": 18 } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Invalid date range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/reports/accounting": { "get": { "tags": [ "Reports" ], "summary": "Accounting report", "description": "Returns aggregated accounting metrics for a given period.", "operationId": "92ac44009059aa6917d4644d017166d2", "parameters": [ { "name": "from", "in": "query", "description": "Start date (defaults to start of current month)", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-01-01" } }, { "name": "to", "in": "query", "description": "End date (defaults to end of current month)", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-01-31" } } ], "responses": { "200": { "description": "Accounting report data", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "properties": { "period": { "properties": { "from": { "type": "string", "format": "date", "example": "2024-01-01" }, "to": { "type": "string", "format": "date", "example": "2024-01-31" } }, "type": "object" }, "total_entries": { "description": "Total journal entries", "type": "integer", "example": 45 }, "posted": { "description": "Number of posted entries", "type": "integer", "example": 38 } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Invalid date range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/reports/inventory": { "get": { "tags": [ "Reports" ], "summary": "Inventory report", "description": "Returns aggregated inventory movement metrics for a given period.", "operationId": "77b04d3b89a966171916dcaa74ed86f3", "parameters": [ { "name": "from", "in": "query", "description": "Start date (defaults to start of current month)", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-01-01" } }, { "name": "to", "in": "query", "description": "End date (defaults to end of current month)", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-01-31" } } ], "responses": { "200": { "description": "Inventory report data", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "properties": { "period": { "properties": { "from": { "type": "string", "format": "date", "example": "2024-01-01" }, "to": { "type": "string", "format": "date", "example": "2024-01-31" } }, "type": "object" }, "total_moves": { "description": "Total stock movements", "type": "integer", "example": 120 }, "total_in": { "description": "Total quantity received (positive moves)", "type": "number", "format": "float", "example": 500 }, "total_out": { "description": "Total quantity shipped (absolute value of negative moves)", "type": "number", "format": "float", "example": 350 } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Invalid date range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/requisitions": { "get": { "tags": [ "Requisitions" ], "summary": "List requisitions", "description": "Returns a paginated list of purchase requisitions with optional status filter.", "operationId": "4cb0d058e8ed7edfdbe9ec817c046a5b", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "draft", "pending", "approved", "rejected" ] } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of requisitions", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Requisition" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Requisitions" ], "summary": "Create requisition", "description": "Creates a new purchase requisition in draft status.", "operationId": "156bf0b3024252194ced014d56d8037c", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "requested_date", "lines" ], "properties": { "requested_date": { "type": "string", "format": "date", "example": "2024-01-15" }, "required_by_date": { "type": "string", "format": "date", "example": "2024-02-15", "nullable": true }, "justification": { "type": "string", "nullable": true, "maxLength": 1000 }, "lines": { "type": "array", "items": { "properties": { "product_id": { "type": "integer", "nullable": true }, "description": { "type": "string", "nullable": true, "maxLength": 500 }, "quantity": { "type": "number", "format": "float", "example": 10 }, "unit": { "type": "string", "nullable": true, "maxLength": 50 }, "estimated_unit_price": { "type": "number", "format": "float", "nullable": true } }, "type": "object" }, "minItems": 1 } }, "type": "object" } } } }, "responses": { "201": { "description": "Requisition created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/Requisition" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/requisitions/{id}": { "get": { "tags": [ "Requisitions" ], "summary": "Get requisition by ID", "description": "Returns a single requisition with its line items.", "operationId": "71e6193310508edb6e5e0ba6975b0cbf", "parameters": [ { "name": "id", "in": "path", "description": "Requisition ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Requisition details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Requisition" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Requisitions" ], "summary": "Update requisition", "description": "Updates a draft requisition and replaces its lines.", "operationId": "466d8cb2b17b687f3cd1b05013fb59de", "parameters": [ { "name": "id", "in": "path", "description": "Requisition ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "requested_date", "lines" ], "properties": { "requested_date": { "type": "string", "format": "date" }, "required_by_date": { "type": "string", "format": "date", "nullable": true }, "justification": { "type": "string", "nullable": true, "maxLength": 1000 }, "lines": { "type": "array", "items": { "properties": { "product_id": { "type": "integer", "nullable": true }, "description": { "type": "string", "nullable": true, "maxLength": 500 }, "quantity": { "type": "number", "format": "float" }, "unit": { "type": "string", "nullable": true, "maxLength": 50 }, "estimated_unit_price": { "type": "number", "format": "float", "nullable": true } }, "type": "object" }, "minItems": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Requisition updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Requisition" } }, "type": "object" } } } }, "400": { "description": "Cannot update non-draft requisition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Requisitions" ], "summary": "Delete requisition", "description": "Deletes a draft requisition.", "operationId": "af4d3ceda6274746651abd88b6f2b05c", "parameters": [ { "name": "id", "in": "path", "description": "Requisition ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Requisition deleted" }, "400": { "description": "Cannot delete non-draft requisition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/requisitions/{id}/approve": { "post": { "tags": [ "Requisitions" ], "summary": "Approve requisition", "description": "Approves a draft or pending requisition.", "operationId": "4738047f325d9c79a2156d0571f6f7f2", "parameters": [ { "name": "id", "in": "path", "description": "Requisition ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Requisition approved", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Requisition" } }, "type": "object" } } } }, "400": { "description": "Requisition cannot be approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/requisitions/{id}/reject": { "post": { "tags": [ "Requisitions" ], "summary": "Reject requisition", "description": "Rejects a draft or pending requisition.", "operationId": "613d2b84dd55b90f6874d6b756fa102e", "parameters": [ { "name": "id", "in": "path", "description": "Requisition ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Requisition rejected", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Requisition" } }, "type": "object" } } } }, "400": { "description": "Requisition cannot be rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/requisitions/{id}/submit": { "post": { "tags": [ "Requisitions" ], "summary": "Submit requisition", "description": "Submits a draft requisition for approval by setting status to pending.", "operationId": "b1c599a306f684c2c28db1b43e6c7b7e", "parameters": [ { "name": "id", "in": "path", "description": "Requisition ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Requisition submitted", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Requisition" } }, "type": "object" } } } }, "422": { "description": "Requisition is not in draft status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/requisitions/{id}/convert-to-purchase-order": { "post": { "tags": [ "Requisitions" ], "summary": "Convert requisition to purchase order", "description": "Creates a purchase order from an approved requisition.", "operationId": "fa9781cc9afd2c31415ba08ad3868c6d", "parameters": [ { "name": "id", "in": "path", "description": "Requisition ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "vendor_id" ], "properties": { "vendor_id": { "description": "Vendor ID for the purchase order", "type": "integer", "example": 1 } }, "type": "object" } } } }, "responses": { "201": { "description": "Purchase order created from requisition", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "properties": { "purchase_order_id": { "type": "integer", "example": 5 }, "reference": { "type": "string", "example": "PO-20240115-0042" }, "message": { "type": "string", "example": "Purchase order created from requisition." } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Requisition is not approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/sales-orders": { "get": { "tags": [ "Sales Orders" ], "summary": "List sales orders", "description": "Returns a paginated list of sales orders with optional search and filtering.", "operationId": "4c7c2bd6c8452887346a6bed06eeb224", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Search by reference or customer name", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "draft", "confirmed", "delivered", "cancelled" ] } }, { "name": "customer_id", "in": "query", "description": "Filter by customer ID", "required": false, "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of sales orders", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SalesOrder" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Sales Orders" ], "summary": "Create sales order", "description": "Creates a new sales order.", "operationId": "9aa4f30d695cf89251ccaf2086c9cb5a", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "customer_id" ], "properties": { "customer_id": { "type": "integer", "example": 1 }, "quote_id": { "type": "integer", "example": 1, "nullable": true }, "currency_id": { "type": "integer", "example": 1, "nullable": true }, "exchange_rate": { "type": "number", "format": "float", "example": 1, "nullable": true }, "order_date": { "type": "string", "format": "date", "example": "2024-01-15", "nullable": true }, "expected_delivery_date": { "type": "string", "format": "date", "example": "2024-01-30", "nullable": true }, "subtotal": { "type": "number", "format": "float", "example": 1000, "nullable": true }, "discount_amount": { "type": "number", "format": "float", "example": 0, "nullable": true }, "tax_amount": { "type": "number", "format": "float", "example": 150, "nullable": true }, "total": { "type": "number", "format": "float", "example": 1150, "nullable": true }, "shipping_address": { "type": "string", "nullable": true, "maxLength": 500 }, "notes": { "type": "string", "nullable": true, "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Sales order created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/SalesOrder" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/sales-orders/{id}": { "get": { "tags": [ "Sales Orders" ], "summary": "Get sales order by ID", "description": "Returns a single sales order with line items.", "operationId": "bfa8af99b519e9e39069d4fbbec0e36f", "parameters": [ { "name": "id", "in": "path", "description": "Sales order ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Sales order details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/SalesOrder" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Sales Orders" ], "summary": "Update sales order", "description": "Updates a draft sales order.", "operationId": "8005eb84211f7a8d26b2af67d7cfc948", "parameters": [ { "name": "id", "in": "path", "description": "Sales order ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "customer_id" ], "properties": { "customer_id": { "type": "integer", "example": 1 }, "quote_id": { "type": "integer", "nullable": true }, "currency_id": { "type": "integer", "nullable": true }, "exchange_rate": { "type": "number", "format": "float", "nullable": true }, "order_date": { "type": "string", "format": "date", "nullable": true }, "expected_delivery_date": { "type": "string", "format": "date", "nullable": true }, "subtotal": { "type": "number", "format": "float", "nullable": true }, "discount_amount": { "type": "number", "format": "float", "nullable": true }, "tax_amount": { "type": "number", "format": "float", "nullable": true }, "total": { "type": "number", "format": "float", "nullable": true }, "shipping_address": { "type": "string", "nullable": true, "maxLength": 500 }, "notes": { "type": "string", "nullable": true, "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Sales order updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/SalesOrder" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Sales Orders" ], "summary": "Delete sales order", "description": "Soft-deletes a sales order.", "operationId": "2a9cf4245e12aa364058ec0f2ff29ac7", "parameters": [ { "name": "id", "in": "path", "description": "Sales order ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Sales order deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/sales-orders/{id}/confirm": { "post": { "tags": [ "Sales Orders" ], "summary": "Confirm sales order", "description": "Transitions a draft sales order to confirmed status.", "operationId": "15f188900a32898d0a84958d5c5618c4", "parameters": [ { "name": "id", "in": "path", "description": "Sales order ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Sales order confirmed", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/SalesOrder" } }, "type": "object" } } } }, "422": { "description": "Order is not in draft status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/sales-orders/{id}/convert-to-invoice": { "post": { "tags": [ "Sales Orders" ], "summary": "Convert sales order to invoice", "description": "Creates an invoice from a confirmed sales order.", "operationId": "37a1d6cdfe378db79fa466c44f12f7ec", "parameters": [ { "name": "id", "in": "path", "description": "Sales order ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Invoice created from sales order", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Invoice" } }, "type": "object" } } } }, "422": { "description": "Order must be in confirmed status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/sales-orders/{id}/pdf": { "get": { "tags": [ "Sales Orders" ], "summary": "Get sales order PDF URL", "description": "Returns the download URL for the sales order PDF.", "operationId": "e6cfe0c5a030279c2d370c9ed0f745e2", "parameters": [ { "name": "id", "in": "path", "description": "Sales order ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "PDF download URL", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "properties": { "url": { "type": "string", "format": "uri", "example": "https://app.example.com/pdf/sales-orders/1" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/sales-orders/{id}/cancel": { "post": { "tags": [ "Sales Orders" ], "summary": "Cancel sales order", "description": "Cancels a sales order that has not been delivered or already cancelled.", "operationId": "a9c983684d37ed5e5a84fd45cfffcf75", "parameters": [ { "name": "id", "in": "path", "description": "Sales order ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "cancellation_reason": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Sales order cancelled", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/SalesOrder" } }, "type": "object" } } } }, "422": { "description": "Sales order cannot be cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/sales-orders/{id}/lines": { "get": { "tags": [ "Sales Orders" ], "summary": "List sales order lines", "description": "Returns all line items for a sales order.", "operationId": "e5c4cd9743a0d58b44a2102541c66049", "parameters": [ { "name": "id", "in": "path", "description": "Sales order ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of sales order lines", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/serial-numbers": { "get": { "tags": [ "Serial Numbers" ], "summary": "List serial numbers", "description": "Returns a paginated list of serial numbers with optional filtering.", "operationId": "50bbaf5323d964a4cbe23648fd867391", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "product_id", "in": "query", "description": "Filter by product ID", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "available", "sold", "in_repair", "retired" ] } }, { "name": "search", "in": "query", "description": "Search by serial number", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of serial numbers" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Serial Numbers" ], "summary": "Create serial number", "operationId": "6ee04b13df56b2df02caba3557160046", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "product_id", "serial_number" ], "properties": { "product_id": { "type": "integer", "example": 1 }, "location_id": { "type": "integer", "example": 1, "nullable": true }, "serial_number": { "type": "string", "example": "SN-2026-001", "maxLength": 255 }, "status": { "type": "string", "example": "available", "enum": [ "available", "sold", "in_repair", "retired" ] }, "warranty_expiry": { "type": "string", "format": "date", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Serial number created" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/serial-numbers/{serial_number}": { "get": { "tags": [ "Serial Numbers" ], "summary": "Get serial number by ID", "operationId": "8eaed7ac14353a04955e8efd97d4aedc", "parameters": [ { "name": "serial_number", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Serial number details" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Serial Numbers" ], "summary": "Update serial number", "operationId": "9f5d543f9dffa76da2e04958b01bbec5", "parameters": [ { "name": "serial_number", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "product_id", "serial_number" ], "properties": { "product_id": { "type": "integer" }, "location_id": { "type": "integer", "nullable": true }, "serial_number": { "type": "string", "maxLength": 255 }, "status": { "type": "string", "enum": [ "available", "sold", "in_repair", "retired" ] }, "warranty_expiry": { "type": "string", "format": "date", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Serial number updated" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Serial Numbers" ], "summary": "Delete serial number", "operationId": "41025743a27ad4e598e2cb2ccba3afcc", "parameters": [ { "name": "serial_number", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Serial number deleted" }, "409": { "description": "Cannot delete — serial number is not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/sla-rules": { "get": { "tags": [ "SLA Rules" ], "summary": "List SLA rules", "operationId": "1a4ee0d19c6a26bc912ad84c642a5c3e", "parameters": [ { "name": "priority", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] } }, { "name": "is_active", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "List of SLA rules" } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "SLA Rules" ], "summary": "Create an SLA rule", "operationId": "d1e9ba43a91a8fe64fce6999bb4a226f", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "priority", "first_response_hours", "resolution_hours" ], "properties": { "name": { "type": "string" }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "first_response_hours": { "type": "number", "minimum": 0.1 }, "resolution_hours": { "type": "number", "minimum": 0.1 }, "is_active": { "type": "boolean" }, "business_hours_only": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "201": { "description": "Created" }, "422": { "description": "Validation error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/sla-rules/{id}": { "get": { "tags": [ "SLA Rules" ], "summary": "Get SLA rule by ID", "operationId": "be726a06c93a7d5f990a0b5fcbea805e", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "SLA rule details" }, "404": { "description": "Not found" } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "SLA Rules" ], "summary": "Update an SLA rule", "operationId": "6e68ef236ccc69bf4c9c015c33161b50", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlaRuleRequest" } } } }, "responses": { "200": { "description": "Updated" }, "422": { "description": "Validation error" } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "SLA Rules" ], "summary": "Delete an SLA rule", "operationId": "21abf22e52f83f7565c50240be81265e", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted" }, "422": { "description": "Rule has active tickets" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/stock-adjustments": { "get": { "tags": [ "Stock Adjustments" ], "summary": "List stock adjustments", "description": "Returns a paginated list of stock adjustments with optional filters.", "operationId": "c8a53d62ce2e22dac07e7c2e27f04677", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string" } }, { "name": "warehouse_id", "in": "query", "description": "Filter by warehouse ID", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Paginated list of stock adjustments" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Stock Adjustments" ], "summary": "Create stock adjustment", "operationId": "9ed56ec8b45c3724e1927fb00fda119c", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "warehouse_id" ], "properties": { "warehouse_id": { "type": "integer" }, "reason": { "type": "string", "nullable": true, "maxLength": 500 } }, "type": "object" } } } }, "responses": { "201": { "description": "Stock adjustment created" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/stock-adjustments/{id}": { "get": { "tags": [ "Stock Adjustments" ], "summary": "Get stock adjustment by ID", "operationId": "1145f0e34113fb5a120058ed49d5543f", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Stock adjustment details" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Stock Adjustments" ], "summary": "Update stock adjustment", "description": "Updates a stock adjustment. Only allowed when status is draft.", "operationId": "a0191aa00e802e80dfd58218cfed33e1", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "warehouse_id" ], "properties": { "warehouse_id": { "type": "integer" }, "reason": { "type": "string", "nullable": true, "maxLength": 500 } }, "type": "object" } } } }, "responses": { "200": { "description": "Stock adjustment updated" }, "400": { "description": "Cannot update non-draft adjustment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Stock Adjustments" ], "summary": "Delete stock adjustment", "description": "Deletes a stock adjustment. Only allowed when status is draft.", "operationId": "14e951a1f594af9694cf0ab53250e93d", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Stock adjustment deleted" }, "400": { "description": "Cannot delete non-draft adjustment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/stock-adjustments/{id}/validate": { "post": { "tags": [ "Stock Adjustments" ], "summary": "Validate stock adjustment", "description": "Sets status to posted. Returns error if already posted.", "operationId": "4a52e306dbb92db3ce754f371ece52a0", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Stock adjustment posted" }, "400": { "description": "Already posted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/stock-adjustments/{id}/cancel": { "post": { "tags": [ "Stock Adjustments" ], "summary": "Cancel stock adjustment", "description": "Cancels a draft stock adjustment.", "operationId": "6e45ab7eb3fae960b09bf283d4853100", "parameters": [ { "name": "id", "in": "path", "description": "Stock Adjustment ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Stock adjustment cancelled", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Stock adjustment is not in draft status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/stock-balances": { "get": { "tags": [ "Stock Balances" ], "summary": "List stock balances", "description": "Returns a paginated list of stock balances with optional filters.", "operationId": "e19d6e3a8839ddbe5648a8392d337b11", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "product_id", "in": "query", "description": "Filter by product ID", "required": false, "schema": { "type": "integer" } }, { "name": "warehouse_id", "in": "query", "description": "Filter by warehouse ID (via location)", "required": false, "schema": { "type": "integer" } }, { "name": "location_id", "in": "query", "description": "Filter by location ID", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Paginated list of stock balances" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/stock-balances/{id}": { "get": { "tags": [ "Stock Balances" ], "summary": "Get stock balance by ID", "operationId": "a8980ec0b6aa5ad1ce4c41cb613df146", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Stock balance details" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/stock/valuation": { "get": { "tags": [ "Stock Intelligence" ], "summary": "Stock valuation report", "description": "Returns stock valuation per product per location using AVCO or FIFO method.", "operationId": "1c357ec3d1144b51cd09ea6a8dc57dd2", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "method", "in": "query", "description": "Valuation method", "required": false, "schema": { "type": "string", "default": "avco", "enum": [ "avco", "fifo" ] } }, { "name": "warehouse_id", "in": "query", "description": "Filter by warehouse ID", "required": false, "schema": { "type": "integer" } }, { "name": "product_id", "in": "query", "description": "Filter by product ID", "required": false, "schema": { "type": "integer" } }, { "name": "category_id", "in": "query", "description": "Filter by product category ID", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Stock valuation data" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/stock/alerts": { "get": { "tags": [ "Stock Intelligence" ], "summary": "Low stock alerts", "description": "Returns products where current stock is below their reorder point.", "operationId": "22ad4f4134dca718d73b5692f1fceb4e", "parameters": [ { "name": "warehouse_id", "in": "query", "description": "Filter by warehouse ID", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Low stock alert list" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/stock/expiring": { "get": { "tags": [ "Stock Intelligence" ], "summary": "Expiring stock lots", "description": "Returns stock lots expiring within the given number of days.", "operationId": "42f4547f28ec5f49aa9fc38b196f8a74", "parameters": [ { "name": "days", "in": "query", "description": "Days ahead to check (default: 30)", "required": false, "schema": { "type": "integer", "default": 30 } }, { "name": "warehouse_id", "in": "query", "description": "Filter by warehouse ID", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Expiring lot list" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/stock-lots": { "get": { "tags": [ "Stock Lots" ], "summary": "List stock lots", "description": "Returns a paginated list of stock lots with optional filtering.", "operationId": "3e76473e2aea1407d538ada48784daa4", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "product_id", "in": "query", "description": "Filter by product ID", "required": false, "schema": { "type": "integer" } }, { "name": "warehouse_id", "in": "query", "description": "Filter by warehouse ID (via location)", "required": false, "schema": { "type": "integer" } }, { "name": "is_expired", "in": "query", "description": "Filter expired lots (1=expired, 0=not expired)", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of stock lots" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Stock Lots" ], "summary": "Create stock lot", "operationId": "1f6391f10ce60cc8be725290d519031a", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "product_id", "lot_number" ], "properties": { "product_id": { "type": "integer", "example": 1 }, "location_id": { "type": "integer", "example": 1, "nullable": true }, "lot_number": { "type": "string", "example": "LOT-2026-001", "maxLength": 255 }, "received_date": { "type": "string", "format": "date", "nullable": true }, "expiry_date": { "type": "string", "format": "date", "nullable": true }, "unit_cost": { "type": "number", "format": "float", "example": 10.5, "nullable": true }, "qty_received": { "type": "number", "format": "float", "example": 100, "minimum": 0 }, "qty_remaining": { "type": "number", "format": "float", "example": 100, "minimum": 0 } }, "type": "object" } } } }, "responses": { "201": { "description": "Stock lot created" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/stock-lots/{stock_lot}": { "get": { "tags": [ "Stock Lots" ], "summary": "Get stock lot by ID", "operationId": "ea36637c8523b2fa6a63062d871ae9ea", "parameters": [ { "name": "stock_lot", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Stock lot details" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Stock Lots" ], "summary": "Update stock lot", "operationId": "2877e5870c29de2020190ab340baf16b", "parameters": [ { "name": "stock_lot", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "product_id", "lot_number" ], "properties": { "product_id": { "type": "integer" }, "location_id": { "type": "integer", "nullable": true }, "lot_number": { "type": "string", "maxLength": 255 }, "received_date": { "type": "string", "format": "date", "nullable": true }, "expiry_date": { "type": "string", "format": "date", "nullable": true }, "unit_cost": { "type": "number", "format": "float", "nullable": true }, "qty_received": { "type": "number", "format": "float", "minimum": 0 }, "qty_remaining": { "type": "number", "format": "float", "minimum": 0 } }, "type": "object" } } } }, "responses": { "200": { "description": "Stock lot updated" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Stock Lots" ], "summary": "Delete stock lot", "operationId": "7bd2968fcd4847b9520028c3a0694dc3", "parameters": [ { "name": "stock_lot", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Stock lot deleted" }, "409": { "description": "Cannot delete — lot still has remaining quantity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/ticket-categories": { "get": { "tags": [ "Ticket Categories" ], "summary": "List ticket categories", "operationId": "a5999e0eeb2004b2fef2fe67ceac4262", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 } } ], "responses": { "200": { "description": "List of categories" } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Ticket Categories" ], "summary": "Create a ticket category", "operationId": "0803f55dc318a76dd28e3357b2ac953e", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "color": { "type": "string", "example": "#FF5733", "nullable": true }, "icon": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "sort_order": { "type": "integer" } }, "type": "object" } } } }, "responses": { "201": { "description": "Created" }, "422": { "description": "Validation error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/ticket-categories/{id}": { "get": { "tags": [ "Ticket Categories" ], "summary": "Get ticket category by ID", "operationId": "7f2842a14e108330ce387f4cdf5c9349", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Category details" }, "404": { "description": "Not found" } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Ticket Categories" ], "summary": "Update a ticket category", "operationId": "d23ba22895e189667bcaea3f40e51e3b", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketCategoryRequest" } } } }, "responses": { "200": { "description": "Updated" }, "422": { "description": "Validation error" } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Ticket Categories" ], "summary": "Delete a ticket category", "operationId": "e8cf9aaa097d9123fd7ee9140033ce18", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted" }, "422": { "description": "Category has linked tickets" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/tickets": { "get": { "tags": [ "Support Tickets" ], "summary": "List support tickets", "description": "Returns a paginated list of support tickets with optional filtering.", "operationId": "58016360b2a1361c2775ae34d34a84d5", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "in_progress", "waiting", "resolved", "closed" ] } }, { "name": "priority", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] } }, { "name": "assigned_to", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "customer_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "ticket_category_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "sla_breached", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of tickets" }, "401": { "description": "Unauthenticated" } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Support Tickets" ], "summary": "Create a new ticket", "operationId": "8169964a096efcff7ed542c5011493a0", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "subject", "description" ], "properties": { "subject": { "type": "string" }, "description": { "type": "string" }, "customer_id": { "type": "integer", "nullable": true }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "ticket_category_id": { "type": "integer", "nullable": true }, "assigned_to": { "type": "integer", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Ticket created" }, "422": { "description": "Validation error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/tickets/{id}": { "get": { "tags": [ "Support Tickets" ], "summary": "Get ticket by ID", "operationId": "6bc3075b0670d192fb57083d5a9fca9e", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Ticket details" }, "404": { "description": "Not found" } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Support Tickets" ], "summary": "Update a ticket", "operationId": "5a66c684bc6bea22de783ed2c5c7f715", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertTicketRequest" } } } }, "responses": { "200": { "description": "Ticket updated" }, "422": { "description": "Validation error" } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Support Tickets" ], "summary": "Delete a ticket", "operationId": "27441591b2e9d21d70566240a0857578", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Not found" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/tickets/{id}/assign": { "post": { "tags": [ "Support Tickets" ], "summary": "Assign ticket to a user", "operationId": "b154aabf5b96b32de31607529d4be482", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "user_id" ], "properties": { "user_id": { "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Assigned" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/tickets/{id}/open": { "post": { "tags": [ "Support Tickets" ], "summary": "Set ticket status to open", "operationId": "c0696a4b53fbde5f2447977cd7bb4127", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Status updated" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/tickets/{id}/close": { "post": { "tags": [ "Support Tickets" ], "summary": "Close a ticket", "operationId": "8feeed8a0ca49231dcb738929acc169c", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Ticket closed" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/tickets/{id}/resolve": { "post": { "tags": [ "Support Tickets" ], "summary": "Resolve a ticket", "operationId": "41e4a33acc43d00ec583beccc7cd7edd", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Ticket resolved" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/tickets/{id}/reopen": { "post": { "tags": [ "Support Tickets" ], "summary": "Reopen a resolved/closed ticket", "operationId": "3d28438597875436b0f50a215b47deaf", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Ticket reopened" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/tickets/{id}/tags": { "post": { "tags": [ "Support Tickets" ], "summary": "Add tags to a ticket", "operationId": "c635c54f8cd26afbd6161be15551e98a", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "tags" ], "properties": { "tags": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Tags added" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/tickets/{ticket_id}/replies": { "get": { "tags": [ "Ticket Replies" ], "summary": "List replies for a ticket", "operationId": "279ef5d9e46aef2bcc0e9bbc5db09c93", "parameters": [ { "name": "ticket_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Paginated list of replies" }, "404": { "description": "Ticket not found" } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Ticket Replies" ], "summary": "Add a reply to a ticket", "operationId": "514cde763416f4e1411baf4af67728cd", "parameters": [ { "name": "ticket_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "type": "string", "minLength": 1 }, "is_internal": { "type": "boolean", "default": false } }, "type": "object" } } } }, "responses": { "201": { "description": "Reply created" }, "422": { "description": "Validation error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/tickets/{ticket_id}/replies/{reply_id}": { "put": { "tags": [ "Ticket Replies" ], "summary": "Update a reply (own reply, within 15 minutes)", "operationId": "953736c1b83ca45678526ad3e1f7bafb", "parameters": [ { "name": "ticket_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "reply_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Reply updated" }, "403": { "description": "Forbidden" } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Ticket Replies" ], "summary": "Delete a reply (own reply, within 15 minutes)", "operationId": "73c01cea8fde91a9b2c0f1bbc506d6cc", "parameters": [ { "name": "ticket_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "reply_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted" }, "403": { "description": "Forbidden" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/transfer-orders": { "get": { "tags": [ "Transfer Orders" ], "summary": "List transfer orders", "description": "Returns a paginated list of transfer orders with optional filters.", "operationId": "d5f2182f6bf637acca05adbe2d0334fd", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "search", "in": "query", "description": "Search by reference", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of transfer orders" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Transfer Orders" ], "summary": "Create transfer order", "operationId": "6231c619a3ec6031da42c3810cc26021", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "from_warehouse_id", "to_warehouse_id" ], "properties": { "from_warehouse_id": { "type": "integer" }, "to_warehouse_id": { "type": "integer" }, "scheduled_date": { "type": "string", "format": "date", "nullable": true }, "notes": { "type": "string", "nullable": true, "maxLength": 1000 }, "lines": { "type": "array", "items": { "properties": { "product_id": { "type": "integer" }, "quantity_requested": { "type": "number", "format": "float" } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Transfer order created" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/transfer-orders/{id}": { "get": { "tags": [ "Transfer Orders" ], "summary": "Get transfer order by ID", "operationId": "50241c47cabe737b14413f97192cf559", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Transfer order details with lines" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Transfer Orders" ], "summary": "Update transfer order", "description": "Updates a transfer order. Only allowed when status is draft.", "operationId": "ee93382307d718c00c561297d7c3f241", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "from_warehouse_id", "to_warehouse_id" ], "properties": { "from_warehouse_id": { "type": "integer" }, "to_warehouse_id": { "type": "integer" }, "scheduled_date": { "type": "string", "format": "date", "nullable": true }, "notes": { "type": "string", "nullable": true, "maxLength": 1000 }, "lines": { "type": "array", "items": { "properties": { "product_id": { "type": "integer" }, "quantity_requested": { "type": "number", "format": "float" } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Transfer order updated" }, "400": { "description": "Cannot update non-draft order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Transfer Orders" ], "summary": "Delete transfer order", "description": "Deletes a transfer order. Only allowed when status is draft.", "operationId": "dd6fec9acea9fb940c7b64928e5c1c86", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Transfer order deleted" }, "400": { "description": "Cannot delete non-draft order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/transfer-orders/{id}/validate": { "post": { "tags": [ "Transfer Orders" ], "summary": "Validate transfer order", "description": "Sets status to done and records done_date. Only allowed when status is draft.", "operationId": "1c534bff58fca3a538e6ee61490e0c12", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Transfer order validated" }, "400": { "description": "Cannot validate non-draft order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/transfer-orders/{id}/cancel": { "post": { "tags": [ "Transfer Orders" ], "summary": "Cancel transfer order", "operationId": "2d13a83cc1fa5f45ce3d41ec84e6dc12", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Transfer order cancelled" }, "422": { "description": "Cannot cancel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/unit-categories": { "get": { "tags": [ "Unit Categories" ], "summary": "List unit categories", "description": "Returns a paginated list of unit categories with UOM counts.", "operationId": "dc6531b2991fa71d90bf763d8d76fe64", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "search", "in": "query", "description": "Search by name", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "default": "name" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "default": "asc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of unit categories" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Unit Categories" ], "summary": "Create unit category", "operationId": "031eb2a7978083a645866bfd41282a35", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Weight", "maxLength": 255 }, "name_en": { "type": "string", "example": "Weight", "nullable": true, "maxLength": 255 }, "type": { "type": "string", "example": "reference", "nullable": true, "maxLength": 50 }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Unit category created" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/unit-categories/{unit_category}": { "get": { "tags": [ "Unit Categories" ], "summary": "Get unit category by ID", "operationId": "f5fddf413290c6ae01eadf84fed1c804", "parameters": [ { "name": "unit_category", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Unit category with its UOMs" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Unit Categories" ], "summary": "Update unit category", "operationId": "f5b202bf3b8387c265e272b294fe709f", "parameters": [ { "name": "unit_category", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "name_en": { "type": "string", "nullable": true, "maxLength": 255 }, "type": { "type": "string", "nullable": true, "maxLength": 50 }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Unit category updated" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Unit Categories" ], "summary": "Delete unit category", "operationId": "8e8e348c5aa422cd78a6591764a1181c", "parameters": [ { "name": "unit_category", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Unit category deleted" }, "409": { "description": "Cannot delete — has UOMs linked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/uoms": { "get": { "tags": [ "Units of Measure" ], "summary": "List units of measure", "description": "Returns a paginated list of units of measure with optional filtering.", "operationId": "189ea65d7e1993edf6a5f0674adf31c3", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "search", "in": "query", "description": "Search by name or symbol", "required": false, "schema": { "type": "string" } }, { "name": "unit_category_id", "in": "query", "description": "Filter by unit category ID", "required": false, "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "default": "name" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "default": "asc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of units of measure" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Units of Measure" ], "summary": "Create unit of measure", "operationId": "73fb9a9c1d3092e9cae10c07d3eb9783", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "symbol", "unit_category_id" ], "properties": { "name": { "type": "string", "example": "Kilogram", "maxLength": 255 }, "name_en": { "type": "string", "example": "Kilogram", "nullable": true, "maxLength": 255 }, "symbol": { "type": "string", "example": "kg", "maxLength": 50 }, "unit_category_id": { "type": "integer", "example": 1 }, "factor": { "type": "number", "format": "float", "example": 1 }, "is_base_unit": { "type": "boolean", "example": false }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Unit of measure created" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/uoms/{uom}": { "get": { "tags": [ "Units of Measure" ], "summary": "Get unit of measure by ID", "operationId": "a7580a38e7233a5bb11d1fe92922eaa5", "parameters": [ { "name": "uom", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Unit of measure details" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Units of Measure" ], "summary": "Update unit of measure", "operationId": "b5b76aacdc66a7b1443e0f22e77d8a91", "parameters": [ { "name": "uom", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "symbol", "unit_category_id" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "name_en": { "type": "string", "nullable": true, "maxLength": 255 }, "symbol": { "type": "string", "maxLength": 50 }, "unit_category_id": { "type": "integer" }, "factor": { "type": "number", "format": "float" }, "is_base_unit": { "type": "boolean" }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Unit of measure updated" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Units of Measure" ], "summary": "Delete unit of measure", "operationId": "65c496bc5c963a6fe0e4f6c3f22e5843", "parameters": [ { "name": "uom", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Unit of measure deleted" }, "409": { "description": "Cannot delete — in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/vendors": { "get": { "tags": [ "Vendors" ], "summary": "List vendors", "description": "Returns a paginated list of vendors with optional search and sorting.", "operationId": "70571eaf41927d37483a62a479120c14", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Search by name or email", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of vendors", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Vendor" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Vendors" ], "summary": "Create vendor", "description": "Creates a new vendor record.", "operationId": "41cb5746e19173bc00534506ed4dec0d", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Supplier Inc", "maxLength": 255 }, "email": { "type": "string", "format": "email", "example": "contact@supplier.com", "nullable": true }, "phone": { "type": "string", "example": "+966500000001", "nullable": true, "maxLength": 50 }, "tax_number": { "type": "string", "nullable": true, "maxLength": 50 }, "billing_address": { "type": "string", "nullable": true, "maxLength": 500 }, "city": { "type": "string", "example": "Jeddah", "nullable": true, "maxLength": 100 }, "country": { "type": "string", "example": "SA", "nullable": true, "maxLength": 100 }, "currency_id": { "type": "integer", "example": 1, "nullable": true }, "payment_terms_days": { "type": "integer", "example": 30, "nullable": true }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Vendor created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/Vendor" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/vendors/{id}": { "get": { "tags": [ "Vendors" ], "summary": "Get vendor by ID", "description": "Returns a single vendor record.", "operationId": "a6256b485deb5e7154cade0770a92f87", "parameters": [ { "name": "id", "in": "path", "description": "Vendor ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Vendor details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Vendor" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Vendors" ], "summary": "Update vendor", "description": "Updates an existing vendor record.", "operationId": "112fdefa1f9b234c437813ff2c0dd519", "parameters": [ { "name": "id", "in": "path", "description": "Vendor ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Supplier Inc", "maxLength": 255 }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "type": "string", "nullable": true, "maxLength": 50 }, "tax_number": { "type": "string", "nullable": true, "maxLength": 50 }, "billing_address": { "type": "string", "nullable": true, "maxLength": 500 }, "city": { "type": "string", "nullable": true, "maxLength": 100 }, "country": { "type": "string", "nullable": true, "maxLength": 100 }, "currency_id": { "type": "integer", "nullable": true }, "payment_terms_days": { "type": "integer", "nullable": true }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Vendor updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Vendor" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Vendors" ], "summary": "Delete vendor", "description": "Soft-deletes a vendor record.", "operationId": "03dd87dd5852c877a7531672f8aac7c3", "parameters": [ { "name": "id", "in": "path", "description": "Vendor ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Vendor deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/vendor-evaluations": { "get": { "tags": [ "Vendor Evaluations" ], "summary": "List vendor evaluations", "description": "Returns a paginated list of vendor evaluations with optional filtering.", "operationId": "3915a4902f89683297264b2fc8073b57", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "vendor_id", "in": "query", "description": "Filter by vendor ID", "required": false, "schema": { "type": "integer" } }, { "name": "period_start", "in": "query", "description": "Filter evaluations from this date", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "period_end", "in": "query", "description": "Filter evaluations up to this date", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of vendor evaluations", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Vendor Evaluations" ], "summary": "Create vendor evaluation", "description": "Creates a new vendor evaluation record.", "operationId": "36a972e2b2563b2e1ae0befc133fd2f7", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "vendor_id" ], "properties": { "vendor_id": { "type": "integer", "example": 1 }, "period_start": { "type": "string", "format": "date", "example": "2024-01-01", "nullable": true }, "period_end": { "type": "string", "format": "date", "example": "2024-03-31", "nullable": true }, "quality_score": { "type": "number", "format": "float", "example": 8.5, "nullable": true }, "delivery_score": { "type": "number", "format": "float", "example": 7, "nullable": true }, "price_score": { "type": "number", "format": "float", "example": 9, "nullable": true }, "notes": { "type": "string", "nullable": true }, "purchase_orders_count": { "type": "integer", "example": 12, "nullable": true }, "on_time_delivery_rate": { "type": "number", "format": "float", "example": 91.5, "nullable": true }, "return_rate": { "type": "number", "format": "float", "example": 2, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Vendor evaluation created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/vendor-evaluations/{id}": { "get": { "tags": [ "Vendor Evaluations" ], "summary": "Get vendor evaluation by ID", "description": "Returns a single vendor evaluation record.", "operationId": "06ad8045c8ea636408e6d6a45acaddc7", "parameters": [ { "name": "id", "in": "path", "description": "Vendor evaluation ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Vendor evaluation details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Vendor Evaluations" ], "summary": "Update vendor evaluation", "description": "Updates an existing vendor evaluation.", "operationId": "0ec1694e25941925fdae43091ffd03b7", "parameters": [ { "name": "id", "in": "path", "description": "Vendor evaluation ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "vendor_id" ], "properties": { "vendor_id": { "type": "integer", "example": 1 }, "period_start": { "type": "string", "format": "date", "nullable": true }, "period_end": { "type": "string", "format": "date", "nullable": true }, "quality_score": { "type": "number", "format": "float", "nullable": true }, "delivery_score": { "type": "number", "format": "float", "nullable": true }, "price_score": { "type": "number", "format": "float", "nullable": true }, "notes": { "type": "string", "nullable": true }, "purchase_orders_count": { "type": "integer", "nullable": true }, "on_time_delivery_rate": { "type": "number", "format": "float", "nullable": true }, "return_rate": { "type": "number", "format": "float", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Vendor evaluation updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Vendor Evaluations" ], "summary": "Delete vendor evaluation", "description": "Deletes a vendor evaluation record.", "operationId": "905d97480c1efe1c0a1632733a041660", "parameters": [ { "name": "id", "in": "path", "description": "Vendor evaluation ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Vendor evaluation deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/vendor-evaluations/{id}/score": { "get": { "tags": [ "Vendor Evaluations" ], "summary": "Get vendor evaluation score breakdown", "description": "Returns the overall score, sub-scores, and trend (last 6 evaluations) for the vendor.", "operationId": "a24d890eaa2177d0f442b4f7b093c435", "parameters": [ { "name": "id", "in": "path", "description": "Vendor evaluation ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Score breakdown", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "properties": { "overall_score": { "type": "number", "format": "float", "example": 8.17 }, "quality_score": { "type": "number", "format": "float", "example": 8.5 }, "delivery_score": { "type": "number", "format": "float", "example": 7 }, "price_score": { "type": "number", "format": "float", "example": 9 }, "trend": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/visits": { "get": { "tags": [ "Visits" ], "summary": "List visits", "operationId": "3450f5ca3ef3455c944f1ebfcfc55546", "responses": { "200": { "description": "Paginated visits" }, "401": { "description": "Unauthenticated" } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Visits" ], "summary": "Create visit", "operationId": "1dde93402cb52c440ba5ec362ebea34e", "responses": { "201": { "description": "Visit created" }, "422": { "description": "Validation error" }, "401": { "description": "Unauthenticated" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/visits/{id}": { "get": { "tags": [ "Visits" ], "summary": "Get visit by ID", "operationId": "09856b1c25486e4c1227e8a657253079", "responses": { "200": { "description": "Visit details" }, "404": { "description": "Not found" }, "401": { "description": "Unauthenticated" } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Visits" ], "summary": "Update visit", "operationId": "fd8607edff57fa843dd0256b51cdd4c7", "responses": { "200": { "description": "Visit updated" }, "404": { "description": "Not found" }, "422": { "description": "Validation error" }, "401": { "description": "Unauthenticated" } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Visits" ], "summary": "Delete visit", "operationId": "c4ed446e3299eded91ada8595770a0e8", "responses": { "204": { "description": "Visit deleted" }, "404": { "description": "Not found" }, "401": { "description": "Unauthenticated" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/visits/{id}/check-in": { "post": { "tags": [ "Visits" ], "summary": "Check in to a visit", "operationId": "5af7ce59380698bbd4202e0f350e5e88", "responses": { "200": { "description": "Checked in" }, "400": { "description": "Invalid status transition" }, "404": { "description": "Not found" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/visits/{id}/check-out": { "post": { "tags": [ "Visits" ], "summary": "Check out from a visit", "operationId": "7d4eaa7c06575bfadc74de7fedd6d034", "responses": { "200": { "description": "Checked out" }, "400": { "description": "Invalid status transition" }, "404": { "description": "Not found" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/visits/{id}/cancel": { "post": { "tags": [ "Visits" ], "summary": "Cancel a visit", "operationId": "6d105e54a454b507bd2947aa35abae9e", "responses": { "200": { "description": "Visit cancelled" }, "400": { "description": "Invalid status transition" }, "404": { "description": "Not found" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/warehouses": { "get": { "tags": [ "Warehouses" ], "summary": "List warehouses", "description": "Returns a paginated list of warehouses.", "operationId": "c02e2817482820ff60980bbc552b71af", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Search by name or code", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "name" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "asc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of warehouses", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Warehouse" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Warehouses" ], "summary": "Create warehouse", "description": "Creates a new warehouse.", "operationId": "f05ddde2247f68c87e174cf79fe7e5a3", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Main Warehouse", "maxLength": 255 }, "code": { "type": "string", "example": "WH-MAIN", "nullable": true, "maxLength": 50 }, "address": { "type": "string", "example": "789 Industrial Zone, Riyadh", "nullable": true, "maxLength": 500 }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Warehouse created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/Warehouse" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/warehouses/{id}": { "get": { "tags": [ "Warehouses" ], "summary": "Get warehouse by ID", "description": "Returns a single warehouse record.", "operationId": "fa89d85b8f38ce9518b9401a470da2da", "parameters": [ { "name": "id", "in": "path", "description": "Warehouse ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Warehouse details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Warehouse" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Warehouses" ], "summary": "Update warehouse", "description": "Updates an existing warehouse.", "operationId": "94a361e7d7ba8b38c07046f490a1ea4e", "parameters": [ { "name": "id", "in": "path", "description": "Warehouse ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Main Warehouse", "maxLength": 255 }, "code": { "type": "string", "nullable": true, "maxLength": 50 }, "address": { "type": "string", "nullable": true, "maxLength": 500 }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Warehouse updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Warehouse" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Warehouses" ], "summary": "Delete warehouse", "description": "Deletes a warehouse. Returns an error if the warehouse has existing stock balances.", "operationId": "0c9b9f36f285ebd6f4bc8ed422fc87e4", "parameters": [ { "name": "id", "in": "path", "description": "Warehouse ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Warehouse deleted" }, "422": { "description": "Cannot delete a warehouse with existing stock balances", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/warehouse-locations": { "get": { "tags": [ "Warehouse Locations" ], "summary": "List warehouse locations", "description": "Returns a paginated list of warehouse locations, optionally filtered by warehouse.", "operationId": "ed92a8db073415937d259ef4323f6eee", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "warehouse_id", "in": "query", "description": "Filter by warehouse ID", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Paginated list of warehouse locations" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Warehouse Locations" ], "summary": "Create warehouse location", "operationId": "df5a11cce81d1c3e7b9f269617403fc7", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "warehouse_id", "name" ], "properties": { "warehouse_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "parent_id": { "type": "integer", "nullable": true }, "barcode": { "type": "string", "nullable": true, "maxLength": 100 }, "usage": { "type": "string", "nullable": true, "maxLength": 50 }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "201": { "description": "Warehouse location created" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/warehouse-locations/{id}": { "get": { "tags": [ "Warehouse Locations" ], "summary": "Get warehouse location by ID", "operationId": "ae2d75d828abc284dc8078c843d9a91b", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Warehouse location details" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Warehouse Locations" ], "summary": "Update warehouse location", "operationId": "2341cee055b065495fda28e027274400", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "warehouse_id", "name" ], "properties": { "warehouse_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "parent_id": { "type": "integer", "nullable": true }, "barcode": { "type": "string", "nullable": true, "maxLength": 100 }, "usage": { "type": "string", "nullable": true, "maxLength": 50 }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Warehouse location updated" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Warehouse Locations" ], "summary": "Delete warehouse location", "operationId": "fab202ecf8f975bfbed496f51890a4eb", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Warehouse location deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhooks", "description": "Returns a paginated list of configured webhooks.", "operationId": "ace64a34955390e45536d233f24868be", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "sort", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Paginated list of webhooks", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Webhooks" ], "summary": "Create webhook", "description": "Registers a new webhook endpoint. A signing secret (`whsec_...`) is automatically generated and returned only on creation.", "operationId": "c82745a0a480491a8e6a43b781532468", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "example": "https://yourapp.com/webhooks/erp", "maxLength": 500 }, "events": { "description": "Event types to subscribe to", "type": "array", "items": { "type": "string", "example": "invoice.created" }, "example": [ "invoice.created", "payment.posted" ], "minItems": 1 }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Webhook created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Created" }, "data": { "$ref": "#/components/schemas/Webhook" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Get webhook by ID", "description": "Returns a single webhook configuration.", "operationId": "f56d6a960c7b1021daa6f7f709f9d16d", "parameters": [ { "name": "id", "in": "path", "description": "Webhook ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Webhook details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Webhook" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "Webhooks" ], "summary": "Update webhook", "description": "Updates an existing webhook configuration.", "operationId": "8cf9103d62126da73cc020dc48c562bf", "parameters": [ { "name": "id", "in": "path", "description": "Webhook ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 500 }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Webhook updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": { "$ref": "#/components/schemas/Webhook" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete webhook", "description": "Deletes a webhook configuration.", "operationId": "c32180ef88f8403cb024f7244778f88f", "parameters": [ { "name": "id", "in": "path", "description": "Webhook ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Webhook deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/workflow/pending": { "get": { "tags": [ "Workflow" ], "summary": "List my pending approvals", "description": "Returns all workflow approvals waiting for the authenticated user's decision.", "operationId": "f7f6c500c2a3a9c11e76c62809d7ec74", "responses": { "200": { "description": "List of pending approvals", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "workflow_instance_id": { "type": "integer" }, "step_order": { "type": "integer" }, "decision": { "type": "string", "enum": [ "pending", "approved", "rejected" ] }, "instance": { "type": "object" } }, "type": "object" } } }, "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/workflow/instances/{instance}": { "get": { "tags": [ "Workflow" ], "summary": "Get workflow instance with timeline", "operationId": "270707840b4809d18510ba0f9f6335b0", "parameters": [ { "name": "instance", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Workflow instance with full approval timeline" }, "404": { "description": "Not found" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/workflow/instances/{instance}/approve": { "post": { "tags": [ "Workflow" ], "summary": "Approve a workflow step", "operationId": "89000897090eaadffe3f988da4256a7c", "parameters": [ { "name": "instance", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "comments": { "type": "string", "nullable": true, "maxLength": 1000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Approved successfully" }, "422": { "description": "Instance is no longer pending" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/workflow/instances/{instance}/reject": { "post": { "tags": [ "Workflow" ], "summary": "Reject a workflow step", "operationId": "a15f0a8eef56c93f3c8d4c959a225997", "parameters": [ { "name": "instance", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "comments" ], "properties": { "comments": { "type": "string", "maxLength": 1000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Rejected successfully" }, "422": { "description": "Instance is no longer pending" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/workflow/instances/{instance}/delegate": { "post": { "tags": [ "Workflow" ], "summary": "Delegate approval to another user", "operationId": "f384ef9d1d5eac717dd50bdc18358fb6", "parameters": [ { "name": "instance", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "delegate_user_id" ], "properties": { "delegate_user_id": { "description": "User ID to delegate approval to", "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Delegated successfully" }, "422": { "description": "Instance is no longer pending" } }, "security": [ { "ApiKeyAuth": [] } ] } } }, "components": { "schemas": { "PaginationMeta": { "properties": { "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 15 }, "total": { "type": "integer", "example": 100 }, "last_page": { "type": "integer", "example": 7 } }, "type": "object" }, "PaginationLinks": { "properties": { "first": { "type": "string", "example": "https://api.example.com/api/v1/customers?page=1", "nullable": true }, "last": { "type": "string", "example": "https://api.example.com/api/v1/customers?page=7", "nullable": true }, "prev": { "type": "string", "example": null, "nullable": true }, "next": { "type": "string", "example": "https://api.example.com/api/v1/customers?page=2", "nullable": true } }, "type": "object" }, "ErrorResponse": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object", "example": { "name": [ "The name field is required." ] }, "nullable": true } }, "type": "object" }, "Customer": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Acme Corp" }, "email": { "type": "string", "format": "email", "example": "info@acme.com", "nullable": true }, "phone": { "type": "string", "example": "+966500000000", "nullable": true }, "tax_number": { "type": "string", "example": "300000000000003", "nullable": true }, "billing_address": { "type": "string", "example": "123 Main St", "nullable": true }, "city": { "type": "string", "example": "Riyadh", "nullable": true }, "country": { "type": "string", "example": "SA", "nullable": true }, "currency_code": { "type": "string", "example": "SAR", "nullable": true }, "credit_limit": { "type": "number", "format": "float", "example": 10000 }, "payment_terms_days": { "type": "integer", "example": 30, "nullable": true }, "is_active": { "type": "boolean", "example": true }, "outstanding_balance": { "type": "number", "format": "float", "example": 5000 }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "Vendor": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Supplier Inc" }, "email": { "type": "string", "format": "email", "example": "contact@supplier.com", "nullable": true }, "phone": { "type": "string", "example": "+966500000001", "nullable": true }, "tax_number": { "type": "string", "example": "300000000000004", "nullable": true }, "billing_address": { "type": "string", "example": "456 Trade Ave", "nullable": true }, "city": { "type": "string", "example": "Jeddah", "nullable": true }, "country": { "type": "string", "example": "SA", "nullable": true }, "is_active": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "Product": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Laptop Pro" }, "sku": { "type": "string", "example": "LAP-001", "nullable": true }, "description": { "type": "string", "example": "High-performance laptop", "nullable": true }, "category_name": { "type": "string", "example": "Electronics", "nullable": true }, "unit_price": { "type": "number", "format": "float", "example": 2500 }, "cost_price": { "type": "number", "format": "float", "example": 1800 }, "is_active": { "type": "boolean", "example": true }, "stock_quantity": { "type": "number", "format": "float", "example": 50 }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "Invoice": { "properties": { "id": { "type": "integer", "example": 1 }, "reference": { "type": "string", "example": "INV-2024-0001" }, "customer": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Acme Corp" } }, "type": "object", "nullable": true }, "currency": { "properties": { "code": { "type": "string", "example": "SAR" } }, "type": "object", "nullable": true }, "invoice_date": { "type": "string", "format": "date", "example": "2024-01-15", "nullable": true }, "due_date": { "type": "string", "format": "date", "example": "2024-02-15", "nullable": true }, "status": { "type": "string", "example": "draft", "enum": [ "draft", "posted", "sent", "paid", "cancelled" ] }, "type": { "type": "string", "example": "standard", "nullable": true }, "subtotal": { "type": "number", "format": "float", "example": 1000 }, "discount_amount": { "type": "number", "format": "float", "example": 0 }, "tax_amount": { "type": "number", "format": "float", "example": 150 }, "total": { "type": "number", "format": "float", "example": 1150 }, "amount_paid": { "type": "number", "format": "float", "example": 0 }, "amount_due": { "type": "number", "format": "float", "example": 1150 }, "is_overdue": { "type": "boolean", "example": false }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "Bill": { "properties": { "id": { "type": "integer", "example": 1 }, "reference": { "type": "string", "example": "BILL-2024-0001", "nullable": true }, "vendor_reference": { "type": "string", "example": "VND-INV-123", "nullable": true }, "vendor": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Supplier Inc" } }, "type": "object", "nullable": true }, "purchase_order": { "properties": { "id": { "type": "integer", "example": 1 }, "reference": { "type": "string", "example": "PO-2024-0001" } }, "type": "object", "nullable": true }, "currency": { "properties": { "code": { "type": "string", "example": "SAR" } }, "type": "object", "nullable": true }, "bill_date": { "type": "string", "format": "date", "example": "2024-01-15", "nullable": true }, "due_date": { "type": "string", "format": "date", "example": "2024-02-15", "nullable": true }, "status": { "type": "string", "example": "draft", "enum": [ "draft", "submitted", "approved", "paid", "cancelled" ] }, "subtotal": { "type": "number", "format": "float", "example": 500 }, "tax_amount": { "type": "number", "format": "float", "example": 75 }, "total": { "type": "number", "format": "float", "example": 575 }, "amount_paid": { "type": "number", "format": "float", "example": 0 }, "amount_due": { "type": "number", "format": "float", "example": 575 }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "SalesOrder": { "properties": { "id": { "type": "integer", "example": 1 }, "reference": { "type": "string", "example": "SO-2024-0001" }, "customer_name": { "type": "string", "example": "Acme Corp", "nullable": true }, "customer_id": { "type": "integer", "example": 1 }, "status": { "type": "string", "example": "draft", "enum": [ "draft", "confirmed", "delivered", "cancelled" ] }, "payment_status": { "type": "string", "example": "unpaid", "nullable": true }, "order_date": { "type": "string", "format": "date", "example": "2024-01-15", "nullable": true }, "total": { "type": "number", "format": "float", "example": 1500 }, "amount_paid": { "type": "number", "format": "float", "example": 0 }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "PurchaseOrder": { "properties": { "id": { "type": "integer", "example": 1 }, "reference": { "type": "string", "example": "PO-2024-0001" }, "vendor_name": { "type": "string", "example": "Supplier Inc", "nullable": true }, "vendor_id": { "type": "integer", "example": 1 }, "status": { "type": "string", "example": "draft", "enum": [ "draft", "submitted", "approved", "received", "cancelled" ] }, "order_date": { "type": "string", "format": "date", "example": "2024-01-15", "nullable": true }, "total": { "type": "number", "format": "float", "example": 2000 }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "Payment": { "properties": { "id": { "type": "integer", "example": 1 }, "reference": { "type": "string", "example": "PAY-2024-0001", "nullable": true }, "type": { "type": "string", "example": "customer_payment", "enum": [ "customer_payment", "vendor_payment" ] }, "payment_date": { "type": "string", "format": "date", "example": "2024-01-15", "nullable": true }, "amount": { "type": "number", "format": "float", "example": 1150 }, "currency_code": { "type": "string", "example": "SAR", "nullable": true }, "method": { "type": "string", "example": "bank_transfer", "nullable": true }, "customer": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Acme Corp" } }, "type": "object", "nullable": true }, "vendor": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Supplier Inc" } }, "type": "object", "nullable": true }, "status": { "type": "string", "example": "draft", "enum": [ "draft", "posted", "cancelled" ] }, "notes": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "Transaction": { "properties": { "id": { "type": "integer", "example": 1 }, "account": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "1001" }, "name": { "type": "string", "example": "Cash" } }, "type": "object", "nullable": true }, "debit": { "type": "number", "format": "float", "example": 1000 }, "credit": { "type": "number", "format": "float", "example": 0 }, "description": { "type": "string", "example": "Payment received", "nullable": true } }, "type": "object" }, "JournalEntry": { "properties": { "id": { "type": "integer", "example": 1 }, "reference": { "type": "string", "example": "JE-2024-0001", "nullable": true }, "entry_date": { "type": "string", "format": "date", "example": "2024-01-15", "nullable": true }, "description": { "type": "string", "example": "Monthly closing entry" }, "status": { "type": "string", "example": "draft", "enum": [ "draft", "posted", "reversed" ] }, "source_type": { "type": "string", "example": "invoice", "nullable": true }, "source_id": { "type": "integer", "example": 1, "nullable": true }, "currency": { "properties": { "code": { "type": "string", "example": "SAR" } }, "type": "object", "nullable": true }, "total_debit": { "type": "number", "format": "float", "example": 1000 }, "is_balanced": { "type": "boolean", "example": true }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "Employee": { "properties": { "id": { "type": "integer", "example": 1 }, "employee_number": { "type": "string", "example": "EMP-001", "nullable": true }, "first_name": { "type": "string", "example": "Ahmed" }, "last_name": { "type": "string", "example": "Al-Rashid" }, "full_name": { "type": "string", "example": "Ahmed Al-Rashid" }, "email": { "type": "string", "format": "email", "example": "ahmed@company.com", "nullable": true }, "phone": { "type": "string", "example": "+966500000002", "nullable": true }, "department": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Finance" } }, "type": "object", "nullable": true }, "position": { "type": "string", "example": "Accountant", "nullable": true }, "employment_type": { "type": "string", "example": "full_time", "nullable": true }, "hire_date": { "type": "string", "format": "date", "example": "2022-06-01", "nullable": true }, "status": { "type": "string", "example": "active", "enum": [ "active", "inactive", "terminated" ] }, "basic_salary": { "type": "number", "format": "float", "example": 8000 }, "is_active": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "LeaveRequest": { "properties": { "id": { "type": "integer", "example": 1 }, "employee": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Ahmed Al-Rashid" } }, "type": "object", "nullable": true }, "leave_type": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Annual Leave" } }, "type": "object", "nullable": true }, "start_date": { "type": "string", "format": "date", "example": "2024-03-01" }, "end_date": { "type": "string", "format": "date", "example": "2024-03-07" }, "days_requested": { "type": "number", "format": "float", "example": 5 }, "status": { "type": "string", "example": "pending", "enum": [ "pending", "approved", "rejected", "cancelled" ] }, "reason": { "type": "string", "example": "Family vacation", "nullable": true }, "rejection_reason": { "type": "string", "nullable": true }, "approved_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "Payroll": { "properties": { "id": { "type": "integer", "example": 1 }, "reference": { "type": "string", "example": "PAY-2024-01", "nullable": true }, "month": { "type": "integer", "example": 1, "maximum": 12, "minimum": 1 }, "year": { "type": "integer", "example": 2024 }, "pay_date": { "type": "string", "format": "date", "example": "2024-01-31", "nullable": true }, "status": { "type": "string", "example": "draft", "enum": [ "draft", "confirmed", "paid" ] }, "total_earnings": { "type": "number", "format": "float", "example": 50000 }, "total_deductions": { "type": "number", "format": "float", "example": 5000 }, "total_net": { "type": "number", "format": "float", "example": 45000 }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "StockMove": { "properties": { "id": { "type": "integer", "example": 1 }, "product": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Laptop Pro" }, "sku": { "type": "string", "example": "LAP-001" } }, "type": "object", "nullable": true }, "from_location": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Main Warehouse" } }, "type": "object", "nullable": true }, "to_location": { "properties": { "id": { "type": "integer", "example": 2 }, "name": { "type": "string", "example": "Shipping Area" } }, "type": "object", "nullable": true }, "quantity": { "type": "number", "format": "float", "example": 10 }, "unit_cost": { "type": "number", "format": "float", "example": 1800 }, "total_cost": { "type": "number", "format": "float", "example": 18000 }, "serial_number": { "type": "string", "nullable": true }, "lot_number": { "type": "string", "nullable": true }, "state": { "type": "string", "example": "draft", "enum": [ "draft", "done", "cancelled" ] }, "source_type": { "type": "string", "example": "purchase_order", "nullable": true }, "source_id": { "type": "integer", "example": 1, "nullable": true }, "done_date": { "type": "string", "format": "date", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "Warehouse": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Main Warehouse" }, "code": { "type": "string", "example": "WH-MAIN", "nullable": true }, "address": { "type": "string", "example": "789 Industrial Zone, Riyadh", "nullable": true }, "is_active": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "Quote": { "properties": { "id": { "type": "integer", "example": 1 }, "reference": { "type": "string", "example": "QT-2024-0001", "nullable": true }, "customer": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Acme Corp" } }, "type": "object", "nullable": true }, "currency": { "properties": { "code": { "type": "string", "example": "SAR" } }, "type": "object", "nullable": true }, "quote_date": { "type": "string", "format": "date", "example": "2024-01-15", "nullable": true }, "expiry_date": { "type": "string", "format": "date", "example": "2024-02-15", "nullable": true }, "status": { "type": "string", "example": "draft", "enum": [ "draft", "sent", "accepted", "rejected", "expired" ] }, "subtotal": { "type": "number", "format": "float", "example": 1000 }, "discount_amount": { "type": "number", "format": "float", "example": 0 }, "tax_amount": { "type": "number", "format": "float", "example": 150 }, "total": { "type": "number", "format": "float", "example": 1150 }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "Lead": { "properties": { "id": { "type": "integer", "example": 1 }, "title": { "type": "string", "example": "Enterprise Software Deal" }, "contact_name": { "type": "string", "example": "John Smith", "nullable": true }, "contact_email": { "type": "string", "format": "email", "example": "john@prospect.com", "nullable": true }, "contact_phone": { "type": "string", "example": "+966500000003", "nullable": true }, "company_name": { "type": "string", "example": "Prospect Ltd", "nullable": true }, "status": { "type": "string", "example": "new", "nullable": true, "enum": [ "new", "contacted", "qualified", "lost", "converted" ] }, "expected_value": { "type": "number", "format": "float", "example": 50000 }, "expected_close_date": { "type": "string", "format": "date", "example": "2024-06-30", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "Opportunity": { "properties": { "id": { "type": "integer", "example": 1 }, "title": { "type": "string", "example": "Enterprise License Deal" }, "customer": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Acme Corp" } }, "type": "object", "nullable": true }, "lead": { "properties": { "id": { "type": "integer", "example": 1 }, "title": { "type": "string", "example": "Enterprise Software Deal" } }, "type": "object", "nullable": true }, "stage": { "type": "string", "example": "proposal", "nullable": true, "enum": [ "qualified", "proposal", "negotiation", "won", "lost" ] }, "probability": { "type": "integer", "example": 60, "nullable": true, "maximum": 100, "minimum": 0 }, "expected_value": { "type": "number", "format": "float", "example": 100000 }, "weighted_value": { "type": "number", "format": "float", "example": 60000 }, "currency": { "properties": { "code": { "type": "string", "example": "SAR" } }, "type": "object", "nullable": true }, "expected_close_date": { "type": "string", "format": "date", "example": "2024-06-30", "nullable": true }, "closed_at": { "type": "string", "format": "date-time", "nullable": true }, "closed_reason": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "Webhook": { "properties": { "id": { "type": "integer", "example": 1 }, "url": { "type": "string", "format": "uri", "example": "https://yourapp.com/webhooks/erp" }, "events": { "type": "array", "items": { "type": "string", "example": "invoice.created" } }, "is_active": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "Visit": { "properties": { "id": { "type": "integer", "example": 1 }, "employee_id": { "type": "integer", "example": 1 }, "customer_id": { "type": "integer", "example": 1, "nullable": true }, "contact_person": { "type": "string", "example": "John Smith", "nullable": true }, "visit_type": { "type": "string", "example": "sales", "nullable": true }, "purpose": { "type": "string", "example": "Product demo", "nullable": true }, "scheduled_at": { "type": "string", "format": "date-time", "nullable": true }, "checked_in_at": { "type": "string", "format": "date-time", "nullable": true }, "checked_out_at": { "type": "string", "format": "date-time", "nullable": true }, "status": { "type": "string", "example": "scheduled", "enum": [ "scheduled", "checked_in", "completed", "cancelled" ] }, "outcome": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "Account": { "properties": { "id": { "type": "integer", "example": 1 }, "parent_id": { "type": "integer", "example": null, "nullable": true }, "code": { "type": "string", "example": "1001" }, "name": { "type": "string", "example": "Cash on Hand" }, "type": { "type": "string", "example": "asset", "enum": [ "asset", "liability", "equity", "income", "expense" ] }, "sub_type": { "type": "string", "example": "cash", "nullable": true, "enum": [ "customer", "vendor", "cash", "bank" ] }, "normal_balance": { "type": "string", "example": "debit", "enum": [ "debit", "credit" ] }, "is_reconcilable": { "type": "boolean", "example": false }, "is_active": { "type": "boolean", "example": true }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "Currency": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "SAR" }, "name": { "type": "string", "example": "Saudi Riyal" }, "symbol": { "type": "string", "example": "ر.س" }, "exchange_rate": { "type": "number", "format": "float", "example": 1 }, "is_base": { "type": "boolean", "example": true }, "is_active": { "type": "boolean", "example": true }, "rate_updated_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "CostCenter": { "properties": { "id": { "type": "integer", "example": 1 }, "parent_id": { "type": "integer", "nullable": true }, "code": { "type": "string", "example": "CC-SALES" }, "name": { "type": "string", "example": "Sales Department" }, "type": { "type": "string", "example": "department", "nullable": true }, "is_active": { "type": "boolean", "example": true }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "BudgetLine": { "properties": { "id": { "type": "integer", "example": 1 }, "account_id": { "type": "integer", "example": 5 }, "cost_center_id": { "type": "integer", "nullable": true }, "period": { "type": "string", "example": "2024-01", "nullable": true }, "amount": { "type": "number", "format": "float", "example": 50000 }, "notes": { "type": "string", "nullable": true } }, "type": "object" }, "Budget": { "properties": { "id": { "type": "integer", "example": 1 }, "fiscal_year_id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "FY2024 Operating Budget" }, "type": { "type": "string", "example": "operating", "nullable": true }, "status": { "type": "string", "example": "draft", "enum": [ "draft", "submitted", "approved", "rejected" ] }, "notes": { "type": "string", "nullable": true }, "approved_at": { "type": "string", "format": "date-time", "nullable": true }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/BudgetLine" } }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "FixedAsset": { "properties": { "id": { "type": "integer", "example": 1 }, "reference": { "type": "string", "example": "FA-20240115-0001" }, "name": { "type": "string", "example": "Company Vehicle" }, "category": { "type": "string", "example": "vehicle", "nullable": true }, "acquisition_date": { "type": "string", "format": "date", "example": "2024-01-15" }, "acquisition_cost": { "type": "number", "format": "float", "example": 120000 }, "residual_value": { "type": "number", "format": "float", "example": 10000 }, "useful_life_months": { "type": "integer", "example": 60 }, "depreciation_method": { "type": "string", "example": "straight_line", "enum": [ "straight_line", "declining_balance" ] }, "accumulated_depreciation": { "type": "number", "format": "float", "example": 0 }, "book_value": { "type": "number", "format": "float", "example": 120000 }, "last_depreciation_date": { "type": "string", "format": "date", "nullable": true }, "status": { "type": "string", "example": "active", "enum": [ "active", "fully_depreciated", "disposed" ] }, "disposal_date": { "type": "string", "format": "date", "nullable": true }, "disposal_proceeds": { "type": "number", "format": "float", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "FiscalYear": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "FY2024" }, "start_date": { "type": "string", "format": "date", "example": "2024-01-01" }, "end_date": { "type": "string", "format": "date", "example": "2024-12-31" }, "status": { "type": "string", "example": "open", "enum": [ "open", "closed", "locked" ] }, "locked_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "BankStatementLine": { "properties": { "id": { "type": "integer", "example": 1 }, "transaction_date": { "type": "string", "format": "date", "example": "2024-01-10" }, "description": { "type": "string", "example": "Customer payment received" }, "bank_reference": { "type": "string", "example": "TXN-98765", "nullable": true }, "debit": { "type": "number", "format": "float", "example": 0 }, "credit": { "type": "number", "format": "float", "example": 5000 }, "status": { "type": "string", "example": "unmatched", "enum": [ "unmatched", "matched" ] }, "matched_transaction_id": { "type": "integer", "nullable": true }, "notes": { "type": "string", "nullable": true } }, "type": "object" }, "BankStatement": { "properties": { "id": { "type": "integer", "example": 1 }, "account_id": { "type": "integer", "example": 3 }, "reference": { "type": "string", "example": "BS-20240115-0001", "nullable": true }, "statement_date": { "type": "string", "format": "date", "example": "2024-01-31" }, "period_from": { "type": "string", "format": "date", "example": "2024-01-01" }, "period_to": { "type": "string", "format": "date", "example": "2024-01-31" }, "opening_balance": { "type": "number", "format": "float", "example": 10000 }, "closing_balance": { "type": "number", "format": "float", "example": 15000 }, "status": { "type": "string", "example": "draft", "enum": [ "draft", "reconciled" ] }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/BankStatementLine" } }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "RecurringJournalEntry": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Monthly Rent Accrual" }, "description": { "type": "string", "nullable": true }, "frequency": { "type": "string", "example": "monthly", "enum": [ "monthly", "quarterly", "semi_annual", "annual" ] }, "start_date": { "type": "string", "format": "date", "example": "2024-01-01" }, "end_date": { "type": "string", "format": "date", "nullable": true }, "next_run_date": { "type": "string", "format": "date", "example": "2024-02-01" }, "last_run_date": { "type": "string", "format": "date", "nullable": true }, "is_active": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "Department": { "properties": { "id": { "type": "integer", "example": 1 }, "parent_id": { "type": "integer", "nullable": true }, "name": { "type": "string", "example": "Finance" }, "code": { "type": "string", "example": "FIN", "nullable": true }, "manager_id": { "type": "integer", "nullable": true }, "is_active": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "LeaveType": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Annual Leave" }, "days_allowed": { "type": "integer", "example": 21 }, "is_paid": { "type": "boolean", "example": true }, "requires_approval": { "type": "boolean", "example": true }, "is_active": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "LeaveBalance": { "properties": { "id": { "type": "integer", "example": 1 }, "employee_id": { "type": "integer", "example": 1 }, "employee_name": { "type": "string", "example": "Ahmed Al-Rashid", "nullable": true }, "leave_type_id": { "type": "integer", "example": 1 }, "leave_type_name": { "type": "string", "example": "Annual Leave", "nullable": true }, "year": { "type": "integer", "example": 2024 }, "allocated": { "type": "number", "format": "float", "example": 21 }, "used": { "type": "number", "format": "float", "example": 5 }, "remaining": { "type": "number", "format": "float", "example": 16 } }, "type": "object" }, "ProductCategory": { "properties": { "id": { "type": "integer", "example": 1 }, "parent_id": { "type": "integer", "nullable": true }, "name": { "type": "string", "example": "Electronics" }, "slug": { "type": "string", "example": "electronics", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "WarehouseLocation": { "properties": { "id": { "type": "integer", "example": 1 }, "warehouse_id": { "type": "integer", "example": 1 }, "parent_id": { "type": "integer", "nullable": true }, "name": { "type": "string", "example": "Rack A-01" }, "barcode": { "type": "string", "example": "LOC-A01", "nullable": true }, "usage": { "type": "string", "example": "storage", "nullable": true }, "is_active": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "TransferOrderLine": { "properties": { "id": { "type": "integer", "example": 1 }, "product_id": { "type": "integer", "example": 1 }, "quantity_requested": { "type": "number", "format": "float", "example": 10 }, "quantity_done": { "type": "number", "format": "float", "example": 0 } }, "type": "object" }, "TransferOrder": { "properties": { "id": { "type": "integer", "example": 1 }, "reference": { "type": "string", "example": "TO-20240115-0001" }, "from_warehouse_id": { "type": "integer", "example": 1 }, "to_warehouse_id": { "type": "integer", "example": 2 }, "status": { "type": "string", "example": "draft", "enum": [ "draft", "done", "cancelled" ] }, "scheduled_date": { "type": "string", "format": "date", "nullable": true }, "done_date": { "type": "string", "format": "date", "nullable": true }, "notes": { "type": "string", "nullable": true }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/TransferOrderLine" } }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "StockAdjustment": { "properties": { "id": { "type": "integer", "example": 1 }, "reference": { "type": "string", "example": "SA-20240115-0001" }, "warehouse_id": { "type": "integer", "example": 1 }, "status": { "type": "string", "example": "draft", "enum": [ "draft", "posted", "cancelled" ] }, "reason": { "type": "string", "example": "Annual stock count correction", "nullable": true }, "journal_entry_id": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "PhysicalInventoryLine": { "properties": { "id": { "type": "integer", "example": 1 }, "product_id": { "type": "integer", "example": 1 }, "product_name": { "type": "string", "example": "Laptop Pro", "nullable": true }, "location_id": { "type": "integer", "nullable": true }, "location_name": { "type": "string", "example": "Rack A-01", "nullable": true }, "system_qty": { "type": "number", "format": "float", "example": 50 }, "counted_qty": { "type": "number", "format": "float", "example": 48 }, "difference_qty": { "type": "number", "format": "float", "example": -2 }, "unit_cost": { "type": "number", "format": "float", "example": 1800 }, "difference_value": { "type": "number", "format": "float", "example": -3600 }, "notes": { "type": "string", "nullable": true } }, "type": "object" }, "PhysicalInventory": { "properties": { "id": { "type": "integer", "example": 1 }, "reference": { "type": "string", "example": "PI-20240115-0001" }, "warehouse_id": { "type": "integer", "example": 1 }, "count_date": { "type": "string", "format": "date", "example": "2024-01-15" }, "status": { "type": "string", "example": "draft", "enum": [ "draft", "in_progress", "validated" ] }, "notes": { "type": "string", "nullable": true }, "validated_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "StockBalance": { "properties": { "id": { "type": "integer", "example": 1 }, "product_id": { "type": "integer", "example": 1 }, "location_id": { "type": "integer", "example": 1, "nullable": true }, "quantity": { "type": "number", "format": "float", "example": 48 }, "avg_cost": { "type": "number", "format": "float", "example": 1800 }, "total_value": { "type": "number", "format": "float", "example": 86400 } }, "type": "object" }, "RequisitionLine": { "properties": { "id": { "type": "integer", "example": 1 }, "product_id": { "type": "integer", "nullable": true }, "description": { "type": "string", "example": "Office supplies", "nullable": true }, "quantity": { "type": "number", "format": "float", "example": 10 }, "unit": { "type": "string", "example": "pcs", "nullable": true }, "estimated_unit_price": { "type": "number", "format": "float", "example": 50, "nullable": true } }, "type": "object" }, "Requisition": { "properties": { "id": { "type": "integer", "example": 1 }, "reference": { "type": "string", "example": "REQ-20240115-0001" }, "status": { "type": "string", "example": "draft", "enum": [ "draft", "pending", "approved", "rejected", "converted" ] }, "requested_date": { "type": "string", "format": "date", "example": "2024-01-15" }, "required_by_date": { "type": "string", "format": "date", "nullable": true }, "justification": { "type": "string", "nullable": true }, "approved_at": { "type": "string", "format": "date-time", "nullable": true }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/RequisitionLine" } }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "GrnLine": { "properties": { "id": { "type": "integer", "example": 1 }, "product_id": { "type": "integer", "example": 1 }, "purchase_order_line_id": { "type": "integer", "nullable": true }, "quantity_received": { "type": "number", "format": "float", "example": 5 }, "unit_cost": { "type": "number", "format": "float", "example": 400, "nullable": true } }, "type": "object" }, "GoodsReceivedNote": { "properties": { "id": { "type": "integer", "example": 1 }, "reference": { "type": "string", "example": "GRN-20240115-0001" }, "purchase_order_id": { "type": "integer", "nullable": true }, "warehouse_id": { "type": "integer", "example": 1 }, "received_date": { "type": "string", "format": "date", "example": "2024-01-15" }, "status": { "type": "string", "example": "draft", "enum": [ "draft", "validated", "posted" ] }, "notes": { "type": "string", "nullable": true }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/GrnLine" } }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "OpportunityActivity": { "properties": { "id": { "type": "integer", "example": 1 }, "opportunity_id": { "type": "integer", "example": 1 }, "user_id": { "type": "integer", "nullable": true }, "type": { "type": "string", "example": "call", "enum": [ "note", "call", "email", "meeting", "task" ] }, "title": { "type": "string", "example": "Follow-up call with Acme" }, "description": { "type": "string", "nullable": true }, "scheduled_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "CannedReplyRequest": { "required": [ "title", "body" ], "properties": { "title": { "type": "string", "maxLength": 200 }, "body": { "type": "string" }, "category": { "type": "string", "nullable": true, "maxLength": 100 }, "shortcut": { "type": "string", "nullable": true, "maxLength": 50 } }, "type": "object" }, "SlaRuleRequest": { "required": [ "name", "priority", "first_response_hours", "resolution_hours" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "first_response_hours": { "type": "number", "minimum": 0.1 }, "resolution_hours": { "type": "number", "minimum": 0.1 }, "is_active": { "type": "boolean", "nullable": true }, "business_hours_only": { "type": "boolean", "nullable": true } }, "type": "object" }, "TicketCategoryRequest": { "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "nullable": true }, "color": { "type": "string", "example": "#FF5733", "nullable": true }, "icon": { "type": "string", "nullable": true, "maxLength": 100 }, "is_active": { "type": "boolean", "nullable": true }, "sort_order": { "type": "integer", "nullable": true, "minimum": 0 } }, "type": "object" }, "UpsertTicketRequest": { "required": [ "subject", "description" ], "properties": { "subject": { "type": "string", "maxLength": 255 }, "description": { "type": "string" }, "customer_id": { "type": "integer", "nullable": true }, "priority": { "type": "string", "nullable": true, "enum": [ "low", "medium", "high", "urgent" ] }, "ticket_category_id": { "type": "integer", "nullable": true }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "nullable": true }, "assigned_to": { "type": "integer", "nullable": true } }, "type": "object" }, "OvertimeRequest": { "properties": { "id": { "type": "integer", "example": 1 }, "employee_id": { "type": "integer", "example": 1 }, "employee": { "properties": { "id": { "type": "integer", "example": 1 }, "full_name": { "type": "string", "example": "Ahmed Al-Rashid" } }, "type": "object", "nullable": true }, "overtime_date": { "type": "string", "format": "date", "example": "2026-05-21" }, "overtime_hours": { "type": "number", "format": "float", "example": 2.5 }, "day_type": { "type": "string", "example": "regular", "nullable": true, "enum": [ "regular", "friday", "holiday" ] }, "rate_multiplier": { "type": "number", "format": "float", "example": 1.5 }, "hourly_rate": { "type": "number", "format": "float", "example": 50 }, "overtime_amount": { "type": "number", "format": "float", "example": 187.5 }, "status": { "type": "string", "example": "pending", "enum": [ "pending", "approved", "rejected", "paid" ] }, "approved_by": { "type": "integer", "nullable": true }, "approved_at": { "type": "string", "format": "date-time", "nullable": true }, "payroll_id": { "type": "integer", "nullable": true }, "notes": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "PayrollComponent": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Housing Allowance" }, "code": { "type": "string", "example": "HOUSING" }, "type": { "type": "string", "example": "earning", "enum": [ "earning", "deduction", "tax" ] }, "calculation": { "type": "string", "example": "percentage", "enum": [ "fixed", "percentage" ] }, "value": { "type": "number", "format": "float", "example": 25 }, "formula": { "type": "string", "nullable": true }, "is_taxable": { "type": "boolean", "example": false }, "is_active": { "type": "boolean", "example": true }, "account_id": { "type": "integer", "nullable": true }, "account": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Salaries Expense" }, "code": { "type": "string", "example": "6100" } }, "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "Eos": { "properties": { "employee_id": { "type": "integer", "example": 1, "nullable": true }, "employee_number": { "type": "string", "example": "EMP-001", "nullable": true }, "full_name": { "type": "string", "example": "Ahmed Al-Rashid", "nullable": true }, "hire_date": { "type": "string", "format": "date", "nullable": true }, "termination_date": { "type": "string", "format": "date", "nullable": true }, "termination_reason": { "type": "string", "nullable": true }, "eos_accrued_days": { "type": "number", "format": "float", "nullable": true }, "eos_total_amount": { "type": "number", "format": "float", "nullable": true }, "leave_encashment_amount": { "type": "number", "format": "float", "nullable": true }, "basic_salary": { "type": "number", "format": "float", "nullable": true } }, "type": "object" }, "GosiSubmission": { "properties": { "id": { "type": "integer", "example": 1 }, "reference": { "type": "string", "example": "GOSI-2024-01", "nullable": true }, "period": { "type": "string", "example": "2024-01", "nullable": true }, "year": { "type": "integer", "example": 2024 }, "month": { "type": "integer", "example": 1 }, "status": { "type": "string", "example": "draft", "enum": [ "draft", "submitted", "accepted", "rejected" ] }, "total_employees": { "type": "integer", "example": 50 }, "total_salaries": { "type": "number", "format": "float", "example": 250000 }, "total_employee_contribution": { "type": "number", "format": "float", "example": 12500 }, "total_employer_contribution": { "type": "number", "format": "float", "example": 12500 }, "submitted_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "Project": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Website Redesign" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "example": "active", "enum": [ "draft", "active", "on_hold", "completed", "cancelled" ] }, "start_date": { "type": "string", "format": "date", "nullable": true }, "end_date": { "type": "string", "format": "date", "nullable": true }, "budget": { "type": "number", "format": "float", "nullable": true }, "actual_cost": { "type": "number", "format": "float", "example": 0 }, "customer_id": { "type": "integer", "nullable": true }, "manager_id": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "ProjectMilestone": { "properties": { "id": { "type": "integer", "example": 1 }, "project_id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Phase 1 Delivery" }, "due_date": { "type": "string", "format": "date", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "is_completed": { "type": "boolean", "example": false }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "ProjectTask": { "properties": { "id": { "type": "integer", "example": 1 }, "project_id": { "type": "integer", "example": 1 }, "title": { "type": "string", "example": "Design mockups" }, "status": { "type": "string", "example": "todo", "enum": [ "todo", "in_progress", "done", "cancelled" ] }, "priority": { "type": "string", "example": "medium", "nullable": true, "enum": [ "low", "medium", "high" ] }, "assigned_to": { "type": "integer", "nullable": true }, "due_date": { "type": "string", "format": "date", "nullable": true }, "estimated_hours": { "type": "number", "format": "float", "example": 8 }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" }, "ProjectTimeEntry": { "properties": { "id": { "type": "integer", "example": 1 }, "project_id": { "type": "integer", "example": 1 }, "task_id": { "type": "integer", "nullable": true }, "user_id": { "type": "integer", "example": 1 }, "hours": { "type": "number", "format": "float", "example": 4 }, "date": { "type": "string", "format": "date", "example": "2024-01-15" }, "billable": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:00:00+00:00" } }, "type": "object" } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "description": "Enter your API key in format: erp_sk_...\\n\\nCan be provided via Authorization: Bearer header or X-Api-Key header.", "name": "Authorization", "in": "header" } } }, "tags": [ { "name": "Customers", "description": "Customer management" }, { "name": "Vendors", "description": "Vendor management" }, { "name": "Products", "description": "Product catalogue management" }, { "name": "Invoices", "description": "Customer invoice management" }, { "name": "Bills", "description": "Vendor bill management" }, { "name": "Sales Orders", "description": "Sales order management" }, { "name": "Purchase Orders", "description": "Purchase order management" }, { "name": "Payments", "description": "Payment management" }, { "name": "Journal Entries", "description": "Accounting journal entry management" }, { "name": "Employees", "description": "Employee management" }, { "name": "Leave Requests", "description": "Employee leave request management" }, { "name": "Payroll", "description": "Payroll run management" }, { "name": "Inventory", "description": "Stock movement management" }, { "name": "Warehouses", "description": "Warehouse management" }, { "name": "Quotes", "description": "Quotation management" }, { "name": "Leads", "description": "CRM lead management" }, { "name": "Opportunities", "description": "CRM opportunity management" }, { "name": "Visits", "description": "Field visit management" }, { "name": "Webhooks", "description": "Outbound webhook management" }, { "name": "Reports", "description": "Business reports and analytics" }, { "name": "Accounts", "description": "Chart of accounts management" }, { "name": "Currencies", "description": "Currency and exchange rate management" }, { "name": "Cost Centers", "description": "Cost center management" }, { "name": "Budgets", "description": "Budget planning and approval" }, { "name": "Fixed Assets", "description": "Fixed asset lifecycle management" }, { "name": "Fiscal Years", "description": "Fiscal year management" }, { "name": "Bank Statements", "description": "Bank statement reconciliation" }, { "name": "Recurring Journal Entries", "description": "Recurring journal entry templates" }, { "name": "Departments", "description": "HR department management" }, { "name": "Leave Types", "description": "Leave type configuration" }, { "name": "Leave Balances", "description": "Employee leave balance management" }, { "name": "Product Categories", "description": "Product category management" }, { "name": "Warehouse Locations", "description": "Warehouse location management" }, { "name": "Transfer Orders", "description": "Inter-warehouse stock transfer management" }, { "name": "Stock Adjustments", "description": "Manual stock adjustment management" }, { "name": "Physical Inventory", "description": "Physical stock count management" }, { "name": "Stock Balances", "description": "Real-time stock balance enquiry" }, { "name": "Requisitions", "description": "Purchase requisition management" }, { "name": "Goods Received Notes", "description": "Goods received note management" }, { "name": "Opportunity Activities", "description": "CRM opportunity activity management" }, { "name": "Workflow", "description": "Dynamic approval workflow — submit, approve, reject, delegate" }, { "name": "Employee Cars", "description": "Company vehicle assignment & document expiry tracking" }, { "name": "GOSI", "description": "Monthly GOSI submission management" }, { "name": "ESS Auth", "description": "Employee Self-Service authentication (login / logout / refresh)" }, { "name": "ESS Profile", "description": "Employee self-service — profile and leave balances" }, { "name": "ESS Payslips", "description": "Employee self-service — payslip retrieval" }, { "name": "ESS Leaves", "description": "Employee self-service — leave request submission and tracking" }, { "name": "ESS Loans", "description": "Employee self-service — loan/advance submission and tracking" }, { "name": "ESS HR Letters", "description": "Employee self-service — HR letter requests" }, { "name": "ESS Approvals", "description": "Employee self-service — manager approval inbox" }, { "name": "Accounting Periods", "description": "Accounting Periods" }, { "name": "Advance Payments", "description": "Advance Payments" }, { "name": "Canned Replies", "description": "Canned Replies" }, { "name": "Currency Revaluation", "description": "Currency Revaluation" }, { "name": "End of Service", "description": "End of Service" }, { "name": "Expense Categories", "description": "Expense Categories" }, { "name": "Expenses", "description": "Expenses" }, { "name": "Leave Accrual", "description": "Leave Accrual" }, { "name": "Opening Balances", "description": "Opening Balances" }, { "name": "Overtime Requests", "description": "Overtime Requests" }, { "name": "Payment Allocations", "description": "Payment Allocations" }, { "name": "Payroll Components", "description": "Payroll Components" }, { "name": "Projects", "description": "Projects" }, { "name": "Project Milestones", "description": "Project Milestones" }, { "name": "Project Tasks", "description": "Project Tasks" }, { "name": "Project Time Entries", "description": "Project Time Entries" }, { "name": "Serial Numbers", "description": "Serial Numbers" }, { "name": "SLA Rules", "description": "SLA Rules" }, { "name": "Stock Intelligence", "description": "Stock Intelligence" }, { "name": "Stock Lots", "description": "Stock Lots" }, { "name": "Ticket Categories", "description": "Ticket Categories" }, { "name": "Support Tickets", "description": "Support Tickets" }, { "name": "Ticket Replies", "description": "Ticket Replies" }, { "name": "Unit Categories", "description": "Unit Categories" }, { "name": "Units of Measure", "description": "Units of Measure" }, { "name": "Vendor Evaluations", "description": "Vendor Evaluations" } ], "security": [ { "ApiKeyAuth": [] } ] }