{ "openapi": "3.0.0", "info": { "title": "Matendes HRM API Documentation", "description": "API documentation for the Matendes HRM Platform", "contact": { "email": "support@matendes.com" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" }, "version": "1.0.0" }, "servers": [ { "url": "http://my-default-host.com", "description": "Matendes HRM API Server" } ], "paths": { "/admin/notification-configs": { "get": { "tags": [ "Notification Configuration" ], "summary": "Get all notification configurations", "operationId": "283385d2ea6120c3f85fb99cc66169ee", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Filter by tenant ID", "required": false, "schema": { "type": "integer" } }, { "name": "company_id", "in": "query", "description": "Filter by company ID", "required": false, "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "description": "Number of records per page", "required": false, "schema": { "type": "integer", "example": 15 } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationConfig" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Notification Configuration" ], "summary": "Create a new notification configuration", "operationId": "156f38aa615619f6f3df8cbae2ad9538", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email_enabled", "sms_enabled", "default_channel", "email_driver", "email_host", "email_port", "email_from_address", "email_from_name", "email_rate_limit", "sms_rate_limit", "is_active" ], "properties": { "tenant_id": { "description": "Tenant ID (for system-wide config if null)", "type": "integer", "nullable": true }, "company_id": { "description": "Company ID (for company-specific config if null)", "type": "integer", "nullable": true }, "email_enabled": { "type": "boolean", "example": true }, "sms_enabled": { "type": "boolean", "example": false }, "default_channel": { "type": "string", "enum": [ "email", "sms", "both" ], "example": "email" }, "email_driver": { "type": "string", "example": "smtp" }, "email_host": { "type": "string", "example": "smtp.mailtrap.io" }, "email_port": { "type": "integer", "example": 2525 }, "email_username": { "type": "string", "example": "user@example.com", "nullable": true }, "email_password": { "type": "string", "example": "password", "nullable": true }, "email_encryption": { "type": "string", "enum": [ "tls", "ssl" ], "example": "tls", "nullable": true }, "email_from_address": { "type": "string", "format": "email", "example": "no-reply@example.com" }, "email_from_name": { "type": "string", "example": "HRM System" }, "sms_provider": { "type": "string", "enum": [ "twilio", "nexmo" ], "example": "twilio", "nullable": true }, "twilio_enabled": { "type": "boolean", "example": true, "nullable": true }, "twilio_sid": { "type": "string", "example": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "nullable": true }, "twilio_token": { "type": "string", "example": "your_twilio_token", "nullable": true }, "twilio_from": { "type": "string", "example": "+15017122661", "nullable": true }, "nexmo_enabled": { "type": "boolean", "example": false, "nullable": true }, "nexmo_key": { "type": "string", "example": "your_nexmo_key", "nullable": true }, "nexmo_secret": { "type": "string", "example": "your_nexmo_secret", "nullable": true }, "nexmo_from": { "type": "string", "example": "NEXMO", "nullable": true }, "notification_settings": { "description": "JSON object for specific notification settings", "type": "object", "nullable": true }, "email_rate_limit": { "type": "integer", "example": 60 }, "sms_rate_limit": { "type": "integer", "example": 10 }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Notification configuration created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/NotificationConfig" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/admin/notification-configs/{id}": { "get": { "tags": [ "Notification Configuration" ], "summary": "Get a specific notification configuration by ID", "operationId": "955eea42e72cd28f44dcd54e71435098", "parameters": [ { "name": "id", "in": "path", "description": "ID of the notification configuration to retrieve", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/NotificationConfig" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Configuration not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Notification Configuration" ], "summary": "Update a specific notification configuration by ID", "operationId": "57cb980860fc1791fdc9cd108551af12", "parameters": [ { "name": "id", "in": "path", "description": "ID of the notification configuration to update", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "tenant_id": { "description": "Tenant ID (for system-wide config if null)", "type": "integer", "nullable": true }, "company_id": { "description": "Company ID (for company-specific config if null)", "type": "integer", "nullable": true }, "email_enabled": { "type": "boolean", "example": true }, "sms_enabled": { "type": "boolean", "example": false }, "default_channel": { "type": "string", "enum": [ "email", "sms", "both" ], "example": "email" }, "email_driver": { "type": "string", "example": "smtp" }, "email_host": { "type": "string", "example": "smtp.mailtrap.io" }, "email_port": { "type": "integer", "example": 2525 }, "email_username": { "type": "string", "example": "user@example.com", "nullable": true }, "email_password": { "type": "string", "example": "password", "nullable": true }, "email_encryption": { "type": "string", "enum": [ "tls", "ssl" ], "example": "tls", "nullable": true }, "email_from_address": { "type": "string", "format": "email", "example": "no-reply@example.com" }, "email_from_name": { "type": "string", "example": "HRM System" }, "sms_provider": { "type": "string", "enum": [ "twilio", "nexmo" ], "example": "twilio", "nullable": true }, "twilio_enabled": { "type": "boolean", "example": true, "nullable": true }, "twilio_sid": { "type": "string", "example": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "nullable": true }, "twilio_token": { "type": "string", "example": "your_twilio_token", "nullable": true }, "twilio_from": { "type": "string", "example": "+15017122661", "nullable": true }, "nexmo_enabled": { "type": "boolean", "example": false, "nullable": true }, "nexmo_key": { "type": "string", "example": "your_nexmo_key", "nullable": true }, "nexmo_secret": { "type": "string", "example": "your_nexmo_secret", "nullable": true }, "nexmo_from": { "type": "string", "example": "NEXMO", "nullable": true }, "notification_settings": { "description": "JSON object for specific notification settings", "type": "object", "nullable": true }, "email_rate_limit": { "type": "integer", "example": 60 }, "sms_rate_limit": { "type": "integer", "example": 10 }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Notification configuration updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/NotificationConfig" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Configuration not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Notification Configuration" ], "summary": "Delete a specific notification configuration by ID", "operationId": "d5db3bbc0ac9fcdcf0c2133a4b12f0dc", "parameters": [ { "name": "id", "in": "path", "description": "ID of the notification configuration to delete", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Notification configuration deleted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Configuration not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/admin/notification-configs/{id}/test-email": { "post": { "tags": [ "Notification Configuration" ], "summary": "Test email connection for a notification configuration", "operationId": "1ce25858ab372964712dd051991ae2b7", "parameters": [ { "name": "id", "in": "path", "description": "ID of the notification configuration to test", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Email test successful", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Configuration not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Email test failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/admin/notification-configs/{id}/test-sms": { "post": { "tags": [ "Notification Configuration" ], "summary": "Test SMS connection for a notification configuration", "operationId": "c7f492ddf78cbd9929d502a81401a96c", "parameters": [ { "name": "id", "in": "path", "description": "ID of the notification configuration to test", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "SMS test successful", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Configuration not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "SMS test failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/admin/notification-configs/{id}/send-test-notification": { "post": { "tags": [ "Notification Configuration" ], "summary": "Send a test notification (email or SMS)", "operationId": "247374e332a9b2750d2235752a2f3af4", "parameters": [ { "name": "id", "in": "path", "description": "ID of the notification configuration to use", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "channel", "recipient", "message" ], "properties": { "channel": { "type": "string", "enum": [ "email", "sms" ], "example": "email" }, "recipient": { "type": "string", "example": "test@example.com" }, "message": { "type": "string", "example": "This is a test message." } }, "type": "object" } } } }, "responses": { "200": { "description": "Test notification sent successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Configuration not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Test notification failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/admin/notification-types": { "get": { "tags": [ "Notification Configuration" ], "summary": "Get all available notification types and their variables", "operationId": "67b5daf8340244a894d2e4cfcefd350c", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/NotificationType" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/admin/notification-templates": { "get": { "tags": [ "Notification Templates" ], "summary": "Get all notification templates", "operationId": "2dafa1cb3f4bf16dfe8e0b9cd759ecb4", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Filter by tenant ID", "required": false, "schema": { "type": "integer" } }, { "name": "company_id", "in": "query", "description": "Filter by company ID", "required": false, "schema": { "type": "integer" } }, { "name": "type", "in": "query", "description": "Filter by template type", "required": false, "schema": { "type": "string" } }, { "name": "channel", "in": "query", "description": "Filter by channel (email, sms)", "required": false, "schema": { "type": "string", "enum": [ "email", "sms" ] } }, { "name": "language", "in": "query", "description": "Filter by language (e.g., en, es)", "required": false, "schema": { "type": "string" } }, { "name": "is_system", "in": "query", "description": "Filter by system templates", "required": false, "schema": { "type": "boolean" } }, { "name": "per_page", "in": "query", "description": "Number of records per page", "required": false, "schema": { "type": "integer", "example": 15 } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationTemplate" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Notification Templates" ], "summary": "Create a new notification template", "operationId": "e93aaf1a80704d66e3a0ed183465a600", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "type", "channel", "name", "content", "is_active", "language" ], "properties": { "tenant_id": { "description": "Tenant ID (for system-wide template if null)", "type": "integer", "nullable": true }, "company_id": { "description": "Company ID (for company-specific template if null)", "type": "integer", "nullable": true }, "type": { "type": "string", "example": "welcome" }, "channel": { "type": "string", "enum": [ "email", "sms" ], "example": "email" }, "name": { "type": "string", "example": "Welcome Email" }, "subject": { "type": "string", "example": "Welcome to our platform!", "nullable": true }, "content": { "type": "string", "example": "Hello {{user_name}}, welcome to {{company_name}}!" }, "variables": { "type": "array", "items": { "type": "string" }, "example": [ "user_name", "company_name" ], "nullable": true }, "is_active": { "type": "boolean", "example": true }, "language": { "type": "string", "example": "en" }, "description": { "type": "string", "example": "Email sent to new users upon registration.", "nullable": true }, "settings": { "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Notification template created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/NotificationTemplate" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error or duplicate template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/admin/notification-templates/{id}": { "get": { "tags": [ "Notification Templates" ], "summary": "Get a specific notification template by ID", "operationId": "215483e2163da282b4d683eaab870ea3", "parameters": [ { "name": "id", "in": "path", "description": "ID of the notification template to retrieve", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/NotificationTemplate" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Notification Templates" ], "summary": "Update a specific notification template by ID", "operationId": "6ffe0fd1daf30aaa7d1d175dfb64e5a6", "parameters": [ { "name": "id", "in": "path", "description": "ID of the notification template to update", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "content", "is_active", "language" ], "properties": { "name": { "type": "string", "example": "Updated Welcome Email" }, "subject": { "type": "string", "example": "Updated Welcome Subject!", "nullable": true }, "content": { "type": "string", "example": "Updated content for {{user_name}}." }, "variables": { "type": "array", "items": { "type": "string" }, "example": [ "user_name" ], "nullable": true }, "is_active": { "type": "boolean", "example": false }, "description": { "type": "string", "example": "Updated description.", "nullable": true }, "settings": { "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Notification template updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/NotificationTemplate" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "System templates cannot be modified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Notification Templates" ], "summary": "Delete a specific notification template by ID", "operationId": "8997c887e212cbf24d0a510e3275a1a1", "parameters": [ { "name": "id", "in": "path", "description": "ID of the notification template to delete", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Notification template deleted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "System templates cannot be deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/admin/notification-templates/{id}/duplicate": { "post": { "tags": [ "Notification Templates" ], "summary": "Duplicate a notification template", "operationId": "aed6bd8e8b30bc1f6ae86aab49944279", "parameters": [ { "name": "id", "in": "path", "description": "ID of the notification template to duplicate", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Copy of Welcome Email" }, "tenant_id": { "description": "New tenant ID for the duplicated template", "type": "integer", "nullable": true }, "company_id": { "description": "New company ID for the duplicated template", "type": "integer", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Template duplicated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/NotificationTemplate" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/admin/notification-templates/{id}/preview": { "post": { "tags": [ "Notification Templates" ], "summary": "Preview a notification template with provided variables", "operationId": "70f1f0f7e94970ab83d7e542cb211f87", "parameters": [ { "name": "id", "in": "path", "description": "ID of the notification template to preview", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "variables" ], "properties": { "variables": { "type": "object", "example": { "user_name": "John Doe", "company_name": "Acme Corp" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/NotificationTemplatePreview" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error or missing variables", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/admin/notification-templates/{id}/variables": { "get": { "tags": [ "Notification Templates" ], "summary": "Get required and available variables for a notification template", "operationId": "054339b1a2412d536e68832561516f78", "parameters": [ { "name": "id", "in": "path", "description": "ID of the notification template", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "required_variables": { "type": "array", "items": { "type": "string" }, "example": [ "user_name" ] }, "available_variables": { "type": "array", "items": { "type": "string" }, "example": [ "user_name", "company_name", "login_url" ] } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/admin/notification-templates/system": { "get": { "tags": [ "Notification Templates" ], "summary": "Get all system notification templates, grouped by type and channel", "operationId": "20d2de05fbd18578165d8af6ca22de84", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemTemplateGroup" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/admin/notification-templates/{id}/reset-to-system": { "post": { "tags": [ "Notification Templates" ], "summary": "Reset a custom notification template to its system default", "operationId": "835ab0ce190e0919461802e5e00e8485", "parameters": [ { "name": "id", "in": "path", "description": "ID of the custom notification template to reset", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Template reset to system defaults", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/NotificationTemplate" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Cannot reset system templates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Template or system template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/admin/profile": { "get": { "tags": [ "Admin Profile" ], "summary": "Get admin profile information", "operationId": "27cb37d86d5b9b23065465213a4cb903", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/AdminProfile" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Admin Profile" ], "summary": "Update admin profile information", "operationId": "74d025b1a42b8526ce6423541fec4126", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminProfileUpdate" } } } }, "responses": { "200": { "description": "Profile updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/AdminProfile" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/admin/profile/avatar": { "post": { "tags": [ "Admin Profile" ], "summary": "Update profile avatar", "operationId": "9ca74e5b2db1257a0d38cca0f98dc065", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "avatar": { "description": "Image file (JPEG, PNG, JPG, GIF) under 2MB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Avatar updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "properties": { "avatar_url": { "type": "string", "format": "url" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Admin Profile" ], "summary": "Remove profile avatar", "operationId": "af8828e4d3824df046076bec78760e34", "responses": { "200": { "description": "Avatar removed successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/admin/profile/change-password": { "post": { "tags": [ "Admin Profile" ], "summary": "Change admin password", "operationId": "0dc6c7a21a326eb504506e4c660262bd", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminPasswordChange" } } } }, "responses": { "200": { "description": "Password changed successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation failed or incorrect password", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/admin/profile/notifications": { "put": { "tags": [ "Admin Profile" ], "summary": "Update notification preferences", "operationId": "e6a863a07c9a5036d407d9851599a336", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminNotificationPreferences" } } } }, "responses": { "200": { "description": "Notification preferences updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "properties": { "email_notifications": { "type": "boolean" }, "push_notifications": { "type": "boolean" }, "sms_notifications": { "type": "boolean" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/admin/profile/toggle-two-factor": { "post": { "tags": [ "Admin Profile" ], "summary": "Enable/disable two-factor authentication", "operationId": "6f15ecb8978642155ae16d2119003796", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminToggleTwoFactor" } } } }, "responses": { "200": { "description": "Two-factor authentication enabled/disabled successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "properties": { "two_factor_enabled": { "type": "boolean" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation failed or incorrect password", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/admin/profile/sessions": { "get": { "tags": [ "Admin Profile" ], "summary": "Get active login sessions for the admin user", "operationId": "cbe60353ec2fb7816d0095e499530def", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdminLoginSession" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/admin/profile/sessions/{sessionId}": { "delete": { "tags": [ "Admin Profile" ], "summary": "Revoke a specific login session for the admin user", "operationId": "3d0eeb8ddb38403eaf4f6e8dc2d885c5", "parameters": [ { "name": "sessionId", "in": "path", "description": "ID of the session to revoke", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session revoked successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/admin/profile/revoke-all-sessions": { "post": { "tags": [ "Admin Profile" ], "summary": "Revoke all other login sessions for the admin user", "operationId": "2b65126920471724de944611c746834a", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "password" ], "properties": { "password": { "type": "string", "format": "password", "example": "CurrentPassword123!" } }, "type": "object" } } } }, "responses": { "200": { "description": "All sessions revoked successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation failed or incorrect password", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/attendance": { "get": { "tags": [ "Attendance" ], "summary": "Get attendance records", "description": "Get attendance records with filtering", "operationId": "5b862801babfbcbc7fed7e959ccb1bb4", "parameters": [ { "name": "date_from", "in": "query", "description": "Start date for filtering (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "End date for filtering (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "branch_id", "in": "query", "description": "Filter by branch ID", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "description": "Filter by attendance status (e.g., present, late, absent)", "required": false, "schema": { "type": "string" } }, { "name": "employee_id", "in": "query", "description": "Filter by employee ID", "required": false, "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "description": "Number of records per page", "required": false, "schema": { "type": "integer", "example": 20 } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Attendance" } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/attendance/check-in": { "post": { "tags": [ "Attendance" ], "summary": "Check in for attendance", "description": "Check in with various methods", "operationId": "767d38c2a3882905b6132c7afc2f23c3", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "method" ], "properties": { "method": { "type": "string", "enum": [ "face_recognition", "punch", "manual", "qr_scan" ], "example": "punch" }, "employee_id": { "description": "Required if method is manual and user is company admin", "type": "integer", "nullable": true }, "latitude": { "type": "number", "format": "float", "example": 34.052235, "nullable": true }, "longitude": { "type": "number", "format": "float", "example": -118.243683, "nullable": true }, "face_data": { "description": "Required if method is face_recognition", "type": "string", "nullable": true }, "qr_code": { "description": "Required if method is qr_scan", "type": "string", "nullable": true }, "punch_code": { "description": "Required if method is punch", "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Checked in successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "attendance": { "$ref": "#/components/schemas/Attendance" }, "status": { "type": "string" }, "check_in_time": { "type": "string", "format": "time" } }, "type": "object" } } } }, "400": { "description": "Bad Request (e.g., method validation failed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden (e.g., attendance method not enabled)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Employee not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict (e.g., already checked in)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/attendance/check-out": { "post": { "tags": [ "Attendance" ], "summary": "Check out from attendance", "description": "Check out", "operationId": "459e4e6331b4abbe6e33f50126e56a79", "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "latitude": { "type": "number", "format": "float", "example": 34.052235, "nullable": true }, "longitude": { "type": "number", "format": "float", "example": -118.243683, "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Checked out successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "attendance": { "$ref": "#/components/schemas/Attendance" }, "total_hours": { "description": "Total working hours in decimal", "type": "number", "format": "float" }, "overtime_hours": { "description": "Overtime hours in decimal", "type": "number", "format": "float" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "No check-in record found for today or employee profile not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict (e.g., already checked out)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/attendance/today": { "get": { "tags": [ "Attendance" ], "summary": "Get today's attendance record and available methods for the authenticated user", "description": "Get today's attendance", "operationId": "118ec1c01a9e913c5b83b8b36afb8db9", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "attendance": { "oneOf": [ { "$ref": "#/components/schemas/Attendance" } ], "nullable": true, "type": "object" }, "available_methods": { "type": "array", "items": { "$ref": "#/components/schemas/AttendanceMethod" } }, "can_check_in": { "type": "boolean" }, "can_check_out": { "type": "boolean" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Employee profile not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/attendance/sync-offline-data": { "post": { "tags": [ "Attendance" ], "summary": "Sync offline attendance data", "description": "Sync offline attendance data", "operationId": "4f5d66b17cd5b639257effb6b7e075c3", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "sync_data": { "type": "array", "items": { "properties": { "action": { "type": "string", "enum": [ "check_in", "check_out" ], "example": "check_in" }, "employee_id": { "type": "integer", "example": 101 }, "timestamp": { "type": "string", "format": "date-time", "example": "2025-08-01T08:55:00Z" }, "method": { "type": "string", "enum": [ "face_recognition", "punch", "manual", "qr_scan" ], "example": "manual" } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Sync completed", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "results": { "type": "array", "items": { "properties": { "employee_id": { "type": "integer" }, "status": { "type": "string", "enum": [ "success", "failed" ] }, "message": { "type": "string" } }, "type": "object" } }, "success_count": { "type": "integer" }, "failed_count": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/attendance/report": { "get": { "tags": [ "Attendance" ], "summary": "Get attendance report", "description": "Get attendance report", "operationId": "658a79b1b821f43566695918203e3d28", "parameters": [ { "name": "date_from", "in": "query", "description": "Start date for the report (YYYY-MM-DD)", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "End date for the report (YYYY-MM-DD)", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "branch_id", "in": "query", "description": "Filter report by branch ID", "required": false, "schema": { "type": "integer" } }, { "name": "employee_id", "in": "query", "description": "Filter report by employee ID", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "attendance": { "type": "array", "items": { "$ref": "#/components/schemas/Attendance" } }, "statistics": { "properties": { "total_records": { "type": "integer" }, "present_days": { "type": "integer" }, "absent_days": { "type": "integer" }, "late_days": { "type": "integer" }, "half_days": { "type": "integer" }, "total_working_hours": { "type": "number", "format": "float" }, "total_overtime_hours": { "type": "number", "format": "float" }, "average_daily_hours": { "type": "number", "format": "float" } }, "type": "object" }, "date_range": { "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/attendance/quick-action": { "post": { "tags": [ "Attendance" ], "summary": "Perform a quick check-in or check-out action", "description": "Quick attendance action (check in/out) for dashboard", "operationId": "9788b7bbb2affec8655f43bdc81c9b83", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "check_in", "check_out" ], "example": "check_in" } }, "type": "object" } } } }, "responses": { "200": { "description": "Quick action successful", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "attendance": { "$ref": "#/components/schemas/Attendance" }, "status": { "type": "string" }, "check_in_time": { "type": "string", "format": "time" }, "total_hours": { "type": "number", "format": "float" }, "overtime_hours": { "type": "number", "format": "float" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Employee profile not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/auth/login": { "post": { "tags": [ "Authentication" ], "summary": "Authenticate user and issue JWT token", "operationId": "99d66635c4992aeaa6aa44ff653d0563", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" }, "password": { "type": "string", "format": "password", "example": "password" }, "two_factor_code": { "type": "string", "example": "123456", "nullable": true }, "device_name": { "type": "string", "example": "My iPhone", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Successful login", "content": { "application/json": { "schema": { "properties": { "user": { "type": "object" }, "token": { "type": "string" }, "token_type": { "type": "string", "example": "Bearer" }, "expires_in": { "type": "integer" } }, "type": "object" } } } }, "422": { "description": "Validation error or authentication failed", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "errors": { "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error" } } } }, "/auth/register": { "post": { "tags": [ "Authentication" ], "summary": "Register a new tenant, company, and admin user", "operationId": "08136088c4862c313b35d6518bab8d3a", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "password", "password_confirmation", "company_name", "subdomain", "plan" ], "properties": { "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "john.doe@example.com" }, "password": { "type": "string", "format": "password", "example": "Password123!" }, "password_confirmation": { "type": "string", "format": "password", "example": "Password123!" }, "company_name": { "type": "string", "example": "Acme Corp" }, "subdomain": { "type": "string", "example": "acmecorp" }, "plan": { "type": "string", "enum": [ "starter", "professional", "enterprise" ], "example": "professional" }, "phone": { "type": "string", "example": "+15551234567", "nullable": true }, "industry": { "type": "string", "example": "Software", "nullable": true }, "company_size": { "type": "string", "example": "51-200", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Registration successful", "content": { "application/json": { "schema": { "properties": { "user": { "type": "object" }, "tenant": { "type": "object" }, "subscription": { "type": "object" }, "token": { "type": "string" }, "token_type": { "type": "string", "example": "Bearer" }, "expires_in": { "type": "integer" }, "message": { "type": "string" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "errors": { "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error" } } } }, "/auth/forgot-password": { "post": { "tags": [ "Authentication" ], "summary": "Send password reset link", "operationId": "fea89d2766defe4ad877001920e3f289", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" } }, "type": "object" } } } }, "responses": { "200": { "description": "Password reset link sent successfully.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "500": { "description": "Server error" } } } }, "/auth/reset-password": { "post": { "tags": [ "Authentication" ], "summary": "Reset user password", "operationId": "b8d03d5b689dcb65d3771f62d4f90a24", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "token", "email", "password", "password_confirmation" ], "properties": { "token": { "type": "string", "example": "some_reset_token" }, "email": { "type": "string", "format": "email", "example": "user@example.com" }, "password": { "type": "string", "format": "password", "example": "NewPassword123!" }, "password_confirmation": { "type": "string", "format": "password", "example": "NewPassword123!" } }, "type": "object" } } } }, "responses": { "200": { "description": "Password has been reset successfully.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "422": { "description": "Validation error or unable to reset password", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "errors": { "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error" } } } }, "/auth/verify-2fa": { "post": { "tags": [ "Authentication" ], "summary": "Verify two-factor authentication code", "operationId": "e3f143637b8c5345fe04431352e938bc", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "two_factor_code" ], "properties": { "two_factor_code": { "type": "string", "example": "123456" }, "device_name": { "type": "string", "example": "My Desktop", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Two-factor verification successful", "content": { "application/json": { "schema": { "properties": { "user": { "type": "object" }, "token": { "type": "string" }, "token_type": { "type": "string", "example": "Bearer" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error or invalid 2FA code", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "errors": { "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/auth/change-password": { "post": { "tags": [ "Authentication" ], "summary": "Change user password", "operationId": "392f5b8efb38f64f049872d18d481cf1", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "current_password", "new_password", "new_password_confirmation" ], "properties": { "current_password": { "type": "string", "format": "password", "example": "OldPassword123!" }, "new_password": { "type": "string", "format": "password", "example": "NewPassword123!" }, "new_password_confirmation": { "type": "string", "format": "password", "example": "NewPassword123!" } }, "type": "object" } } } }, "responses": { "200": { "description": "Password changed successfully.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error or incorrect current password", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "errors": { "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/auth/logout": { "post": { "tags": [ "Authentication" ], "summary": "Log out the authenticated user", "operationId": "6abf3b64a4bc7838d56346f05a5153af", "responses": { "200": { "description": "Logged out successfully.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/auth/me": { "get": { "tags": [ "Authentication" ], "summary": "Get authenticated user details", "operationId": "7edae2cdbaafc10dff8c9c4198b320a2", "responses": { "200": { "description": "User details", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "company": { "type": "object" }, "branch": { "type": "object" }, "role": { "type": "object" }, "employee": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] } }, "/auth/refresh": { "post": { "tags": [ "Authentication" ], "summary": "Refresh JWT token", "operationId": "e7ab7446393758bb71fd1946a349e500", "requestBody": { "content": { "application/json": { "schema": { "properties": { "device_name": { "type": "string", "example": "My Desktop", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Token refreshed successfully.", "content": { "application/json": { "schema": { "properties": { "token": { "type": "string" }, "token_type": { "type": "string", "example": "Bearer" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/auth/2fa/enable": { "post": { "tags": [ "Authentication" ], "summary": "Enable two-factor authentication for the authenticated user", "operationId": "269fcf7b9079b10a9aa68196658642e8", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "password" ], "properties": { "password": { "type": "string", "format": "password", "example": "CurrentPassword123!" } }, "type": "object" } } } }, "responses": { "200": { "description": "Two-factor authentication enabled.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "secret": { "description": "The 2FA secret key", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error or incorrect password", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "errors": { "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/auth/2fa/confirm": { "post": { "tags": [ "Authentication" ], "summary": "Confirm two-factor authentication setup", "operationId": "32f613ed26fec4124b48afa50658a81d", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "code" ], "properties": { "code": { "type": "string", "example": "123456" } }, "type": "object" } } } }, "responses": { "200": { "description": "Two-factor authentication confirmed.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error or invalid code", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "errors": { "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/auth/2fa/disable": { "post": { "tags": [ "Authentication" ], "summary": "Disable two-factor authentication for the authenticated user", "operationId": "84cb5ec54c25a64e00cf1679acb30055", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "password" ], "properties": { "password": { "type": "string", "format": "password", "example": "CurrentPassword123!" } }, "type": "object" } } } }, "responses": { "200": { "description": "Two-factor authentication disabled.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error or incorrect password", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "errors": { "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/auth/2fa/backup-codes": { "post": { "tags": [ "Authentication" ], "summary": "Generate new 2FA backup codes for the authenticated user", "operationId": "7a4974abb1ac50d323a8f45e061897b7", "responses": { "200": { "description": "New backup codes generated.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "backup_codes": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/auth/sessions": { "get": { "tags": [ "Authentication" ], "summary": "Get all active sessions for the authenticated user", "operationId": "9fec720ae6132c4b95d9926dde166717", "responses": { "200": { "description": "List of active sessions", "content": { "application/json": { "schema": { "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/UserSession" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/auth/sessions/{sessionId}": { "delete": { "tags": [ "Authentication" ], "summary": "Revoke a specific session for the authenticated user", "operationId": "024f55dac8a552f2e85b1ef425c9a595", "parameters": [ { "name": "sessionId", "in": "path", "description": "ID of the session to revoke", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Session revoked successfully.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/auth/revoke-all-sessions": { "post": { "tags": [ "Authentication" ], "summary": "Revoke all sessions for the authenticated user", "operationId": "d7add39f1f8ba3bb6b5e323275e2980c", "responses": { "200": { "description": "All sessions revoked successfully.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error" } }, "security": [ { "bearerAuth": [] } ] } }, "/branches": { "get": { "tags": [ "Branches" ], "summary": "Display a listing of branches", "operationId": "db6cd573b152ce1d0e1d6bdcbb72a467", "parameters": [ { "name": "search", "in": "query", "description": "Search branches by name, code, or address", "required": false, "schema": { "type": "string" } }, { "name": "company_id", "in": "query", "description": "Filter branches by company ID", "required": false, "schema": { "type": "integer" } }, { "name": "is_active", "in": "query", "description": "Filter branches by active status", "required": false, "schema": { "type": "boolean" } }, { "name": "per_page", "in": "query", "description": "Number of records per page", "required": false, "schema": { "type": "integer", "example": 15 } }, { "name": "sort_by", "in": "query", "description": "Sort by field (name, code, created_at)", "required": false, "schema": { "type": "string", "enum": [ "name", "code", "created_at" ], "example": "name" } }, { "name": "sort_order", "in": "query", "description": "Sort order (asc, desc)", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "example": "asc" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "branches": { "type": "array", "items": { "$ref": "#/components/schemas/Branch" } }, "pagination": { "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Branches" ], "summary": "Store a newly created branch", "operationId": "078b15285cc6647f009d5e41e30b9cd5", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "code" ], "properties": { "name": { "type": "string", "example": "New York Office" }, "code": { "type": "string", "example": "NYO" }, "company_id": { "description": "Required for Super Admin, otherwise inferred from user", "type": "integer", "nullable": true }, "address": { "type": "string", "example": "123 Main St, New York, NY", "nullable": true }, "phone": { "type": "string", "example": "+12125551234", "nullable": true }, "email": { "type": "string", "format": "email", "example": "nyo@example.com", "nullable": true }, "manager_id": { "description": "ID of the employee managing this branch", "type": "integer", "nullable": true }, "latitude": { "type": "number", "format": "float", "example": 40.7128, "nullable": true }, "longitude": { "type": "number", "format": "float", "example": -74.006, "nullable": true }, "timezone": { "type": "string", "example": "America/New_York", "nullable": true }, "working_hours": { "type": "object", "example": { "monday": { "start": "09:00", "end": "17:00" } }, "nullable": true }, "is_active": { "type": "boolean", "example": true, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Branch created successfully", "content": { "application/json": { "schema": { "properties": { "branch": { "$ref": "#/components/schemas/Branch" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error or branch code already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/branches/{id}": { "get": { "tags": [ "Branches" ], "summary": "Display the specified branch", "operationId": "f20a7f447f6a6874400eb220bfdb6d59", "parameters": [ { "name": "id", "in": "path", "description": "ID of the branch to retrieve", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "branch": { "$ref": "#/components/schemas/Branch" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Branch not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Branches" ], "summary": "Update the specified branch", "operationId": "eb35113dbd6512f69a7c2f209c325d51", "parameters": [ { "name": "id", "in": "path", "description": "ID of the branch to update", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "New York Main Office" }, "code": { "type": "string", "example": "NYMO" }, "address": { "type": "string", "example": "456 Oak Ave, New York, NY", "nullable": true }, "phone": { "type": "string", "example": "+12125555678", "nullable": true }, "email": { "type": "string", "format": "email", "example": "nymo@example.com", "nullable": true }, "manager_id": { "type": "integer", "nullable": true }, "latitude": { "type": "number", "format": "float", "nullable": true }, "longitude": { "type": "number", "format": "float", "nullable": true }, "timezone": { "type": "string", "example": "America/New_York", "nullable": true }, "working_hours": { "type": "object", "nullable": true }, "is_active": { "type": "boolean", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Branch updated successfully", "content": { "application/json": { "schema": { "properties": { "branch": { "$ref": "#/components/schemas/Branch" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Branch not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error or branch code already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Branches" ], "summary": "Remove the specified branch", "operationId": "a626d3e058c7a7a60bb4af7324dd0684", "parameters": [ { "name": "id", "in": "path", "description": "ID of the branch to delete", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Branch deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Branch not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Cannot delete branch with active employees", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "active_employees_count": { "type": "integer" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/branches/{id}/statistics": { "get": { "tags": [ "Branches" ], "summary": "Get branch statistics", "operationId": "888d58a942dc905f96180a6061f73d8a", "parameters": [ { "name": "id", "in": "path", "description": "ID of the branch to retrieve statistics for", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "branch": { "$ref": "#/components/schemas/Branch" }, "statistics": { "properties": { "total_employees": { "type": "integer" }, "active_employees": { "type": "integer" }, "inactive_employees": { "type": "integer" }, "departments": { "type": "array", "items": { "type": "string" } }, "employment_types": { "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Branch not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/branches/companies": { "get": { "tags": [ "Branches" ], "summary": "Get available companies for branch creation", "operationId": "4e6373cd46ddc703077ebd20a5db1398", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "companies": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/companies": { "get": { "tags": [ "Companies" ], "summary": "Display a listing of companies", "operationId": "08ed2ae55723c6a9506353eab8145498", "parameters": [ { "name": "search", "in": "query", "description": "Search companies by name or slug", "required": false, "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "description": "Filter companies by active status", "required": false, "schema": { "type": "boolean" } }, { "name": "per_page", "in": "query", "description": "Number of records per page", "required": false, "schema": { "type": "integer", "example": 15 } }, { "name": "sort_by", "in": "query", "description": "Sort by field (name, slug, created_at)", "required": false, "schema": { "type": "string", "enum": [ "name", "slug", "created_at" ], "example": "name" } }, { "name": "sort_order", "in": "query", "description": "Sort order (asc, desc)", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "example": "asc" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "companies": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } }, "pagination": { "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Companies" ], "summary": "Store a newly created company", "operationId": "d80b2e6cabac7670e3a925121bfb870f", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "slug" ], "properties": { "name": { "type": "string", "example": "New Company Inc." }, "slug": { "type": "string", "example": "new-company-inc" }, "is_active": { "type": "boolean", "example": true, "nullable": true }, "settings": { "type": "object", "example": { "industry": "Tech" }, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Company created successfully", "content": { "application/json": { "schema": { "properties": { "company": { "$ref": "#/components/schemas/Company" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error or company slug already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/companies/{id}": { "get": { "tags": [ "Companies" ], "summary": "Display the specified company", "operationId": "04de43b30ed21f7c223d9faba2342427", "parameters": [ { "name": "id", "in": "path", "description": "ID of the company to retrieve", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "company": { "$ref": "#/components/schemas/Company" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Companies" ], "summary": "Update the specified company", "operationId": "64045036ab84b92fcff8aa9d82256f68", "parameters": [ { "name": "id", "in": "path", "description": "ID of the company to update", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "Updated Company Name" }, "slug": { "type": "string", "example": "updated-company-name" }, "is_active": { "type": "boolean", "example": false, "nullable": true }, "settings": { "type": "object", "example": { "industry": "Finance" }, "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Company updated successfully", "content": { "application/json": { "schema": { "properties": { "company": { "$ref": "#/components/schemas/Company" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error or company slug already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Companies" ], "summary": "Remove the specified company", "operationId": "988db2c604e42e9fd332d321f1e84f47", "parameters": [ { "name": "id", "in": "path", "description": "ID of the company to delete", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Company deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Cannot delete company with associated branches or employees", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/dashboard/super-admin/stats": { "get": { "tags": [ "Dashboard" ], "summary": "Get super admin dashboard statistics", "operationId": "288305b4a21b3c432d20f4c2cae833a9", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "totalCompanies": { "type": "integer", "example": 5 }, "totalBranches": { "type": "integer", "example": 15 }, "totalEmployees": { "type": "integer", "example": 500 }, "totalProjects": { "type": "integer", "example": 120 }, "activeProjects": { "type": "integer", "example": 80 }, "totalRevenue": { "type": "number", "format": "float", "example": 1500000 }, "systemHealth": { "type": "number", "format": "float", "example": 98.5 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/dashboard/super-admin/activities": { "get": { "tags": [ "Dashboard" ], "summary": "Get super admin recent activities", "operationId": "4414b7f27b26bf78f1dd57d19bf1efcc", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "description": { "type": "string", "example": "New company registered" }, "company_name": { "type": "string", "example": "Tech Corp" }, "user_name": { "type": "string", "example": "System" }, "created_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "example": "success" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/dashboard/company-admin/stats": { "get": { "tags": [ "Dashboard" ], "summary": "Get company admin dashboard statistics", "operationId": "d081ff8651db4cbdf1ff010d9d40d579", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "totalBranches": { "type": "integer", "example": 3 }, "totalEmployees": { "type": "integer", "example": 150 }, "totalProjects": { "type": "integer", "example": 30 }, "activeProjects": { "type": "integer", "example": 20 }, "completedProjects": { "type": "integer", "example": 10 }, "todayAttendance": { "type": "number", "format": "float", "example": 92.5 }, "avgAttendanceRate": { "type": "number", "format": "float", "example": 90.1 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/dashboard/company-admin/branch-performance": { "get": { "tags": [ "Dashboard" ], "summary": "Get company admin branch performance data", "operationId": "021a901f9ab6eca3ec1f8818cd75563a", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Main Office" }, "employee_count": { "type": "integer", "example": 100 }, "active_projects": { "type": "integer", "example": 15 }, "attendance_rate": { "type": "number", "format": "float", "example": 91.2 }, "status": { "type": "string", "example": "active" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/dashboard/company-admin/activities": { "get": { "tags": [ "Dashboard" ], "summary": "Get company admin recent activities", "operationId": "8a86dfb0afd779559aaf1023a09a168a", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "description": { "type": "string", "example": "Employee checked in late" }, "branch_name": { "type": "string", "example": "Main Office" }, "user_name": { "type": "string", "example": "Jane Doe" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/dashboard/branch-manager/stats": { "get": { "tags": [ "Dashboard" ], "summary": "Get branch manager dashboard statistics", "operationId": "9f76d97df11d0d081110f2af8127ee75", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "totalEmployees": { "type": "integer", "example": 50 }, "presentToday": { "type": "integer", "example": 45 }, "totalProjects": { "type": "integer", "example": 10 }, "activeProjects": { "type": "integer", "example": 7 }, "pendingLeaves": { "type": "integer", "example": 2 }, "avgAttendanceRate": { "type": "number", "format": "float", "example": 88.9 }, "projectsDeadlineNear": { "type": "integer", "example": 3 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/dashboard/branch-manager/team-attendance": { "get": { "tags": [ "Dashboard" ], "summary": "Get branch manager team attendance data", "operationId": "ae52bc6194829803de3c04ec44c92fe1", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "employee_id": { "type": "integer", "example": 101 }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "department": { "type": "string", "example": "Sales", "nullable": true }, "check_in_time": { "type": "string", "format": "date-time", "nullable": true }, "check_out_time": { "type": "string", "format": "date-time", "nullable": true }, "status": { "type": "string", "example": "present" }, "hours_worked": { "type": "number", "format": "float", "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/dashboard/branch-manager/upcoming-deadlines": { "get": { "tags": [ "Dashboard" ], "summary": "Get branch manager upcoming project deadlines", "operationId": "a09719b7c980201f4adcf7157aa62e95", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "project_id": { "type": "integer", "example": 1 }, "project_name": { "type": "string", "example": "Website Redesign" }, "client_name": { "type": "string", "example": "ABC Corp" }, "end_date": { "type": "string", "format": "date" }, "days_left": { "type": "integer" }, "progress": { "type": "integer" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/dashboard/branch-manager/attendance-calendar": { "get": { "tags": [ "Dashboard" ], "summary": "Get branch manager attendance calendar data for the current month", "operationId": "1e4d3749dac5def428672f727fdce73b", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "date": { "type": "string", "format": "date", "example": "2025-08-01" }, "present": { "type": "integer", "example": 45 }, "total": { "type": "integer", "example": 50 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/dashboard/employee/stats": { "get": { "tags": [ "Dashboard" ], "summary": "Get employee dashboard statistics", "operationId": "2e2f0ea041e60d84e96ca6323a0d62b1", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "todayHours": { "type": "number", "format": "float", "example": 8 }, "weekHours": { "type": "number", "format": "float", "example": 40 }, "monthHours": { "type": "number", "format": "float", "example": 160 }, "assignedProjects": { "type": "integer", "example": 3 }, "completedTasks": { "type": "integer", "example": 20 }, "pendingTasks": { "type": "integer", "example": 5 }, "leaveBalance": { "type": "integer", "example": 10 }, "attendanceRate": { "type": "number", "format": "float", "example": 95.5 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/dashboard/employee/today-attendance": { "get": { "tags": [ "Dashboard" ], "summary": "Get employee today's attendance details", "operationId": "749af4b09f986f5ea177ab72bcc4810d", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "check_in_time": { "type": "string", "format": "date-time", "nullable": true }, "check_out_time": { "type": "string", "format": "date-time", "nullable": true }, "hours_worked": { "type": "number", "format": "float" }, "break_duration": { "type": "number", "format": "float" }, "overtime_hours": { "type": "number", "format": "float" }, "status": { "type": "string", "enum": [ "checked_out", "checked_in", "not_checked_in" ] } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/dashboard/employee/projects": { "get": { "tags": [ "Dashboard" ], "summary": "Get employee assigned projects", "operationId": "0e0062275ef0b64f05432c240f3be735", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Mobile App Development" }, "client_name": { "type": "string", "example": "Client A" }, "role": { "type": "string", "example": "Developer" }, "progress": { "type": "integer" }, "end_date": { "type": "string", "format": "date" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/dashboard/employee/timeline": { "get": { "tags": [ "Dashboard" ], "summary": "Get employee timeline activities", "operationId": "bd29307ab62bbccc9342b1570dcb0169", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "type": { "type": "string", "example": "check_in" }, "description": { "type": "string", "example": "Checked in to work" }, "timestamp": { "type": "string", "format": "date-time" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/employees": { "get": { "tags": [ "Employees" ], "summary": "Display a listing of employees", "operationId": "9aeb15c3a8c5b0b8b9e0931d1673e787", "parameters": [ { "name": "search", "in": "query", "description": "Search employees by name, employee ID, department, or position", "required": false, "schema": { "type": "string" } }, { "name": "company_id", "in": "query", "description": "Filter employees by company ID", "required": false, "schema": { "type": "integer" } }, { "name": "branch_id", "in": "query", "description": "Filter employees by branch ID", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "description": "Filter employees by status (e.g., active, inactive, terminated)", "required": false, "schema": { "type": "string" } }, { "name": "department", "in": "query", "description": "Filter employees by department", "required": false, "schema": { "type": "string" } }, { "name": "position", "in": "query", "description": "Filter employees by position", "required": false, "schema": { "type": "string" } }, { "name": "employment_type", "in": "query", "description": "Filter employees by employment type (e.g., full_time, part_time)", "required": false, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "description": "Number of records per page", "required": false, "schema": { "type": "integer", "example": 15 } }, { "name": "sort_by", "in": "query", "description": "Sort by field (first_name, last_name, employee_id, created_at)", "required": false, "schema": { "type": "string", "enum": [ "first_name", "last_name", "employee_id", "created_at" ], "example": "first_name" } }, { "name": "sort_order", "in": "query", "description": "Sort order (asc, desc)", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "example": "asc" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "employees": { "type": "array", "items": { "$ref": "#/components/schemas/Employee" } }, "pagination": { "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Employees" ], "summary": "Store a newly created employee", "operationId": "2475af536398d342aca2fd7f60f9af3a", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "user_id", "company_id", "branch_id", "role_id", "first_name", "last_name", "hire_date", "employment_type", "status" ], "properties": { "user_id": { "description": "ID of the associated user", "type": "integer" }, "company_id": { "type": "integer" }, "branch_id": { "type": "integer" }, "role_id": { "type": "integer" }, "manager_id": { "type": "integer", "nullable": true }, "employee_id": { "description": "Auto-generated if not provided", "type": "string", "nullable": true }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "type": "string", "nullable": true }, "address": { "type": "object", "nullable": true }, "emergency_contact_name": { "type": "string", "nullable": true }, "emergency_contact_phone": { "type": "string", "nullable": true }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "gender": { "type": "string", "enum": [ "male", "female", "other" ], "nullable": true }, "nationality": { "type": "string", "nullable": true }, "marital_status": { "type": "string", "enum": [ "single", "married", "divorced", "widowed" ], "nullable": true }, "department": { "type": "string", "nullable": true }, "position": { "type": "string", "nullable": true }, "hire_date": { "type": "string", "format": "date" }, "probation_end_date": { "type": "string", "format": "date", "nullable": true }, "contract_end_date": { "type": "string", "format": "date", "nullable": true }, "employment_type": { "type": "string", "enum": [ "full_time", "part_time", "contract", "internship" ] }, "status": { "type": "string", "enum": [ "active", "inactive", "terminated", "resigned" ] }, "salary": { "type": "number", "format": "float", "nullable": true }, "salary_currency": { "type": "string", "nullable": true }, "salary_period": { "type": "string", "enum": [ "hourly", "daily", "weekly", "monthly", "annual" ], "nullable": true }, "hourly_rate": { "type": "number", "format": "float", "nullable": true }, "work_schedule": { "type": "object", "nullable": true }, "work_hours_per_week": { "type": "integer", "nullable": true }, "shift": { "type": "string", "nullable": true }, "benefits": { "type": "array", "items": { "type": "string" }, "nullable": true }, "documents": { "type": "array", "items": { "type": "object" }, "nullable": true }, "skills": { "type": "array", "items": { "type": "string" }, "nullable": true }, "certifications": { "type": "array", "items": { "type": "string" }, "nullable": true }, "education": { "type": "array", "items": { "type": "object" }, "nullable": true }, "notes": { "type": "string", "nullable": true }, "performance_rating": { "type": "number", "format": "float", "nullable": true }, "last_performance_review": { "type": "string", "format": "date", "nullable": true }, "next_performance_review": { "type": "string", "format": "date", "nullable": true }, "goals": { "type": "array", "items": { "type": "string" }, "nullable": true }, "qr_code": { "type": "string", "nullable": true }, "face_encodings": { "type": "array", "items": { "type": "number", "format": "float" }, "nullable": true }, "badge_number": { "type": "string", "nullable": true }, "annual_leave_days": { "type": "integer", "nullable": true }, "sick_leave_days": { "type": "integer", "nullable": true }, "leave_balance": { "type": "number", "format": "float", "nullable": true }, "is_tenant_admin": { "type": "boolean", "nullable": true }, "can_manage_others": { "type": "boolean", "nullable": true }, "is_remote_worker": { "type": "boolean", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Employee created successfully", "content": { "application/json": { "schema": { "properties": { "employee": { "$ref": "#/components/schemas/Employee" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/employees/{id}": { "get": { "tags": [ "Employees" ], "summary": "Display the specified employee", "operationId": "41cfd4a7b54d2f35c31ad2afd9d37f3f", "parameters": [ { "name": "id", "in": "path", "description": "ID of the employee to retrieve", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "employee": { "$ref": "#/components/schemas/Employee" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Employee not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Employees" ], "summary": "Update the specified employee", "operationId": "f1e833660cfbccbfbdef00c84e24c5cb", "parameters": [ { "name": "id", "in": "path", "description": "ID of the employee to update", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "user_id": { "description": "ID of the associated user", "type": "integer" }, "company_id": { "type": "integer" }, "branch_id": { "type": "integer" }, "role_id": { "type": "integer" }, "manager_id": { "type": "integer", "nullable": true }, "employee_id": { "description": "Auto-generated if not provided", "type": "string", "nullable": true }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "type": "string", "nullable": true }, "address": { "type": "object", "nullable": true }, "emergency_contact_name": { "type": "string", "nullable": true }, "emergency_contact_phone": { "type": "string", "nullable": true }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "gender": { "type": "string", "enum": [ "male", "female", "other" ], "nullable": true }, "nationality": { "type": "string", "nullable": true }, "marital_status": { "type": "string", "enum": [ "single", "married", "divorced", "widowed" ], "nullable": true }, "department": { "type": "string", "nullable": true }, "position": { "type": "string", "nullable": true }, "hire_date": { "type": "string", "format": "date" }, "probation_end_date": { "type": "string", "format": "date", "nullable": true }, "contract_end_date": { "type": "string", "format": "date", "nullable": true }, "employment_type": { "type": "string", "enum": [ "full_time", "part_time", "contract", "internship" ] }, "status": { "type": "string", "enum": [ "active", "inactive", "terminated", "resigned" ] }, "salary": { "type": "number", "format": "float", "nullable": true }, "salary_currency": { "type": "string", "nullable": true }, "salary_period": { "type": "string", "enum": [ "hourly", "daily", "weekly", "monthly", "annual" ], "nullable": true }, "hourly_rate": { "type": "number", "format": "float", "nullable": true }, "work_schedule": { "type": "object", "nullable": true }, "work_hours_per_week": { "type": "integer", "nullable": true }, "shift": { "type": "string", "nullable": true }, "benefits": { "type": "array", "items": { "type": "string" }, "nullable": true }, "documents": { "type": "array", "items": { "type": "object" }, "nullable": true }, "skills": { "type": "array", "items": { "type": "string" }, "nullable": true }, "certifications": { "type": "array", "items": { "type": "string" }, "nullable": true }, "education": { "type": "array", "items": { "type": "object" }, "nullable": true }, "notes": { "type": "string", "nullable": true }, "performance_rating": { "type": "number", "format": "float", "nullable": true }, "last_performance_review": { "type": "string", "format": "date", "nullable": true }, "next_performance_review": { "type": "string", "format": "date", "nullable": true }, "goals": { "type": "array", "items": { "type": "string" }, "nullable": true }, "qr_code": { "type": "string", "nullable": true }, "face_encodings": { "type": "array", "items": { "type": "number", "format": "float" }, "nullable": true }, "badge_number": { "type": "string", "nullable": true }, "annual_leave_days": { "type": "integer", "nullable": true }, "sick_leave_days": { "type": "integer", "nullable": true }, "leave_balance": { "type": "number", "format": "float", "nullable": true }, "is_tenant_admin": { "type": "boolean", "nullable": true }, "can_manage_others": { "type": "boolean", "nullable": true }, "is_remote_worker": { "type": "boolean", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Employee updated successfully", "content": { "application/json": { "schema": { "properties": { "employee": { "$ref": "#/components/schemas/Employee" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Employee not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Employees" ], "summary": "Remove the specified employee", "operationId": "12f385259154107ce23e13cf62d2c158", "parameters": [ { "name": "id", "in": "path", "description": "ID of the employee to delete", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Employee deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Employee not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/feature-toggles": { "get": { "tags": [ "Feature Toggles" ], "summary": "Get all feature toggles", "operationId": "08471d577950117808fbb1268df395f7", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/FeatureToggle" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Feature Toggles" ], "summary": "Create a new feature toggle", "operationId": "182582c183d5b507f6716ab5314578ca", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "key", "name", "global_enabled", "scope" ], "properties": { "key": { "type": "string", "example": "new_feature" }, "name": { "type": "string", "example": "New Feature" }, "description": { "type": "string", "example": "Description of the new feature.", "nullable": true }, "global_enabled": { "type": "boolean", "example": true }, "scope": { "type": "string", "enum": [ "global", "company", "branch" ], "example": "global" }, "company_id": { "description": "Required if scope is company or branch", "type": "integer", "nullable": true }, "metadata": { "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Feature toggle created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/FeatureToggle" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/feature-toggles/{key}": { "get": { "tags": [ "Feature Toggles" ], "summary": "Get a specific feature toggle by key", "operationId": "847359ee0817f4f20c47c84a034e27ca", "parameters": [ { "name": "key", "in": "path", "description": "Key of the feature toggle to retrieve", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/FeatureToggle" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Feature toggle not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Feature Toggles" ], "summary": "Update a specific feature toggle", "operationId": "1f41c14af8a956c67cc187f93db299c9", "parameters": [ { "name": "key", "in": "path", "description": "Key of the feature toggle to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "Updated Feature Name", "nullable": true }, "description": { "type": "string", "example": "Updated description.", "nullable": true }, "global_enabled": { "type": "boolean", "example": false, "nullable": true }, "scope": { "type": "string", "enum": [ "global", "company", "branch" ], "example": "company", "nullable": true }, "company_id": { "description": "Required if changing scope to company or branch", "type": "integer", "nullable": true }, "metadata": { "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Feature toggle updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/FeatureToggle" }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Feature toggle not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Feature Toggles" ], "summary": "Delete a specific feature toggle", "operationId": "3409d4cc1bee1c14798ffd96b10a6d5b", "parameters": [ { "name": "key", "in": "path", "description": "Key of the feature toggle to delete", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Feature toggle deleted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Feature toggle not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/feature-toggles/{key}/check": { "get": { "tags": [ "Feature Toggles" ], "summary": "Check if a specific feature is enabled for the current context", "operationId": "8ff9e91e3ba9caa31776da5d0b1bc955", "parameters": [ { "name": "key", "in": "path", "description": "Key of the feature toggle to check", "required": true, "schema": { "type": "string" } }, { "name": "company_id", "in": "query", "description": "Company ID to check feature for (defaults to user's company)", "required": false, "schema": { "type": "integer" } }, { "name": "branch_id", "in": "query", "description": "Branch ID to check feature for (defaults to user's branch)", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "enabled": { "type": "boolean", "example": true }, "feature": { "type": "string", "example": "feature_x" }, "tenant_id": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/feature-toggles/enabled": { "get": { "tags": [ "Feature Toggles" ], "summary": "Get all enabled features for the current context", "operationId": "0f5096b76dbfb9715a142f4b09cfd00d", "parameters": [ { "name": "company_id", "in": "query", "description": "Company ID to get enabled features for (defaults to user's company)", "required": false, "schema": { "type": "integer" } }, { "name": "branch_id", "in": "query", "description": "Branch ID to get enabled features for (defaults to user's branch)", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "enabled_features": { "type": "array", "items": { "type": "string", "example": "feature_x" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/feature-toggles/{key}/toggle-branch": { "post": { "tags": [ "Feature Toggles" ], "summary": "Enable or disable a feature for a specific branch", "operationId": "fd6b25d85e0eede479408c1ea019d5d3", "parameters": [ { "name": "key", "in": "path", "description": "Key of the feature toggle", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "branch_id", "enabled" ], "properties": { "branch_id": { "type": "integer", "example": 1 }, "enabled": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Branch feature toggle updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Feature toggle or branch not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/users": { "get": { "tags": [ "Users" ], "summary": "Display a listing of users/employees", "operationId": "7208c29037df2b8bb02499ba39ed8a78", "parameters": [ { "name": "search", "in": "query", "description": "Search users by first name, last name, email, or employee ID", "required": false, "schema": { "type": "string" } }, { "name": "role_id", "in": "query", "description": "Filter by role ID", "required": false, "schema": { "type": "integer" } }, { "name": "branch_id", "in": "query", "description": "Filter by branch ID", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "description": "Filter by user status (active, inactive, suspended)", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive", "suspended" ] } }, { "name": "per_page", "in": "query", "description": "Number of records per page", "required": false, "schema": { "type": "integer", "example": 15 } }, { "name": "sort_by", "in": "query", "description": "Sort by field (first_name, last_name, email, hire_date, status)", "required": false, "schema": { "type": "string", "enum": [ "first_name", "last_name", "email", "hire_date", "status" ], "example": "first_name" } }, { "name": "sort_order", "in": "query", "description": "Sort order (asc, desc)", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "example": "asc" } }, { "name": "departments", "in": "query", "description": "Filter by department (comma-separated)", "required": false, "schema": { "type": "string" } }, { "name": "hire_date_from", "in": "query", "description": "Filter by hire date from (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "hire_date_to", "in": "query", "description": "Filter by hire date to (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserListResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions or feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Tenant not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Users" ], "summary": "Store a newly created user (employee)", "operationId": "262eb5ca1fdea354023c0a8870442c1e", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "first_name", "last_name", "email", "password", "role_id", "branch_id" ], "properties": { "first_name": { "type": "string", "example": "Jane" }, "last_name": { "type": "string", "example": "Doe" }, "email": { "type": "string", "format": "email", "example": "jane.doe@example.com" }, "password": { "type": "string", "format": "password", "example": "SecurePassword123!" }, "phone": { "type": "string", "example": "+1234567890", "nullable": true }, "role_id": { "description": "ID of the role to assign", "type": "integer" }, "branch_id": { "description": "ID of the branch the employee belongs to", "type": "integer" }, "company_id": { "description": "ID of the company the employee belongs to (optional for super admin)", "type": "integer", "nullable": true }, "manager_id": { "description": "ID of the employee's manager", "type": "integer", "nullable": true }, "department": { "type": "string", "example": "HR", "nullable": true }, "position": { "type": "string", "example": "HR Manager", "nullable": true }, "hire_date": { "type": "string", "format": "date", "example": "2023-01-15", "nullable": true }, "salary": { "type": "number", "format": "float", "example": 50000, "nullable": true }, "employment_type": { "type": "string", "enum": [ "full_time", "part_time", "contract", "intern" ], "example": "full_time", "nullable": true }, "date_of_birth": { "type": "string", "format": "date", "example": "1990-05-20", "nullable": true }, "gender": { "type": "string", "enum": [ "male", "female", "other" ], "example": "female", "nullable": true }, "address": { "type": "string", "example": "123 Employee St, City, Country", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "User created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions, feature not available, or employee limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Tenant not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/users/{id}": { "get": { "tags": [ "Users" ], "summary": "Display the specified user (employee)", "operationId": "6946bbab7898f59a09e3c8e529a38907", "parameters": [ { "name": "id", "in": "path", "description": "ID of the user to retrieve", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions or feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Tenant or user not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Users" ], "summary": "Update the specified user (employee)", "operationId": "05028d02ea3e9a99abd6260cfe05b179", "parameters": [ { "name": "id", "in": "path", "description": "ID of the user to update", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "first_name": { "type": "string", "example": "Jane" }, "last_name": { "type": "string", "example": "Doe" }, "email": { "type": "string", "format": "email", "example": "jane.doe@example.com" }, "phone": { "type": "string", "example": "+1234567890", "nullable": true }, "role_id": { "description": "ID of the role to assign", "type": "integer" }, "branch_id": { "description": "ID of the branch the employee belongs to", "type": "integer" }, "manager_id": { "description": "ID of the employee's manager", "type": "integer", "nullable": true }, "department": { "type": "string", "example": "HR", "nullable": true }, "position": { "type": "string", "example": "HR Manager", "nullable": true }, "hire_date": { "type": "string", "format": "date", "example": "2023-01-15", "nullable": true }, "salary": { "type": "number", "format": "float", "example": 50000, "nullable": true }, "employment_type": { "type": "string", "enum": [ "full_time", "part_time", "contract", "intern" ], "example": "full_time", "nullable": true }, "date_of_birth": { "type": "string", "format": "date", "example": "1990-05-20", "nullable": true }, "gender": { "type": "string", "enum": [ "male", "female", "other" ], "example": "female", "nullable": true }, "address": { "type": "string", "example": "123 Employee St, City, Country", "nullable": true }, "status": { "type": "string", "enum": [ "active", "inactive", "suspended" ], "example": "active", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "User updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions or feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Tenant or user not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Users" ], "summary": "Remove the specified user (employee)", "operationId": "b3d28da5dc9de7fc1bd425f93b54ff7b", "parameters": [ { "name": "id", "in": "path", "description": "ID of the user to delete", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "User deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions or feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Tenant or user not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Cannot delete own account", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/users/profile": { "get": { "tags": [ "Users" ], "summary": "Get current user profile", "operationId": "2464c132da58d2e64538881124f086f4", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfileResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Tenant mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Tenant not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Users" ], "summary": "Update current user profile", "operationId": "22a5d63daba9c5373fb89650466d6a0b", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "first_name": { "type": "string", "example": "Jane" }, "last_name": { "type": "string", "example": "Doe" }, "email": { "type": "string", "format": "email", "example": "jane.doe@example.com" }, "phone": { "type": "string", "example": "+1234567890", "nullable": true }, "date_of_birth": { "type": "string", "format": "date", "example": "1990-05-20", "nullable": true }, "gender": { "type": "string", "enum": [ "male", "female", "other" ], "example": "female", "nullable": true }, "address": { "type": "string", "example": "123 Employee St, City, Country", "nullable": true }, "timezone": { "type": "string", "example": "America/New_York", "nullable": true }, "language": { "type": "string", "example": "en", "nullable": true }, "theme": { "type": "string", "enum": [ "light", "dark", "auto" ], "example": "dark", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Tenant mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Tenant not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "schemas": { "NotificationConfig": { "title": "Notification Configuration Object", "properties": { "id": { "type": "integer", "example": 1 }, "tenant_id": { "type": "integer", "example": 1, "nullable": true }, "company_id": { "type": "integer", "example": 1, "nullable": true }, "email_enabled": { "type": "boolean", "example": true }, "sms_enabled": { "type": "boolean", "example": false }, "default_channel": { "type": "string", "enum": [ "email", "sms", "both" ], "example": "email" }, "email_driver": { "type": "string", "example": "smtp" }, "email_host": { "type": "string", "example": "smtp.mailtrap.io" }, "email_port": { "type": "integer", "example": 2525 }, "email_username": { "type": "string", "example": "user@example.com", "nullable": true }, "email_password": { "type": "string", "example": "password", "nullable": true }, "email_encryption": { "type": "string", "enum": [ "tls", "ssl" ], "example": "tls", "nullable": true }, "email_from_address": { "type": "string", "format": "email", "example": "no-reply@example.com" }, "email_from_name": { "type": "string", "example": "HRM System" }, "sms_provider": { "type": "string", "enum": [ "twilio", "nexmo" ], "example": "twilio", "nullable": true }, "twilio_enabled": { "type": "boolean", "example": true, "nullable": true }, "twilio_sid": { "type": "string", "example": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "nullable": true }, "twilio_token": { "type": "string", "example": "your_twilio_token", "nullable": true }, "twilio_from": { "type": "string", "example": "+15017122661", "nullable": true }, "nexmo_enabled": { "type": "boolean", "example": false, "nullable": true }, "nexmo_key": { "type": "string", "example": "your_nexmo_key", "nullable": true }, "nexmo_secret": { "type": "string", "example": "your_nexmo_secret", "nullable": true }, "nexmo_from": { "type": "string", "example": "NEXMO", "nullable": true }, "notification_settings": { "description": "JSON object for specific notification settings", "type": "object", "nullable": true }, "email_rate_limit": { "type": "integer", "example": 60 }, "sms_rate_limit": { "type": "integer", "example": 10 }, "is_active": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "NotificationType": { "title": "Notification Type Object", "properties": { "name": { "type": "string", "example": "Welcome Message" }, "description": { "type": "string", "example": "Sent when a new user is created" }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "email", "sms" ] } }, "variables": { "type": "array", "items": { "type": "string" } } }, "type": "object" }, "NotificationTemplate": { "title": "Notification Template Object", "properties": { "id": { "type": "integer", "example": 1 }, "tenant_id": { "type": "integer", "example": 1, "nullable": true }, "company_id": { "type": "integer", "example": 1, "nullable": true }, "type": { "type": "string", "example": "welcome" }, "channel": { "type": "string", "enum": [ "email", "sms" ], "example": "email" }, "name": { "type": "string", "example": "Welcome Email" }, "subject": { "type": "string", "example": "Welcome to our platform!", "nullable": true }, "content": { "type": "string", "example": "Hello {{user_name}}, welcome to {{company_name}}!" }, "variables": { "type": "array", "items": { "type": "string" }, "example": [ "user_name", "company_name" ], "nullable": true }, "is_active": { "type": "boolean", "example": true }, "language": { "type": "string", "example": "en" }, "description": { "type": "string", "example": "Email sent to new users upon registration.", "nullable": true }, "settings": { "type": "object", "nullable": true }, "is_system": { "type": "boolean", "example": false }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "NotificationTemplatePreview": { "title": "Notification Template Preview Object", "properties": { "subject": { "type": "string", "example": "Welcome to Acme Corp!" }, "content": { "type": "string", "example": "Hello John Doe, welcome to Acme Corp!" }, "variables_used": { "type": "array", "items": { "type": "string" }, "example": [ "user_name", "company_name" ] }, "available_variables": { "type": "array", "items": { "type": "string" }, "example": [ "user_name", "company_name", "login_url" ] } }, "type": "object" }, "SystemTemplateGroup": { "title": "System Template Group Object", "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "0": { "type": "integer", "property": "id" }, "1": { "type": "string", "property": "type" }, "2": { "type": "string", "property": "channel" }, "3": { "type": "string", "property": "name" }, "4": { "type": "string", "property": "language" }, "5": { "type": "string", "property": "description" } } } } }, "AdminProfile": { "title": "Admin Profile Object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Admin User" }, "email": { "type": "string", "format": "email", "example": "admin@example.com" }, "avatar": { "type": "string", "format": "url", "example": "http://localhost/storage/avatars/avatar.jpg", "nullable": true }, "phone": { "type": "string", "example": "+1234567890", "nullable": true }, "position": { "type": "string", "example": "System Administrator", "nullable": true }, "department": { "type": "string", "example": "IT", "nullable": true }, "bio": { "type": "string", "example": "System admin for HRM platform.", "nullable": true }, "timezone": { "type": "string", "example": "UTC" }, "language": { "type": "string", "example": "en" }, "theme": { "type": "string", "example": "light" }, "notifications": { "properties": { "email_notifications": { "type": "boolean" }, "push_notifications": { "type": "boolean" }, "sms_notifications": { "type": "boolean" } }, "type": "object" }, "security": { "properties": { "two_factor_enabled": { "type": "boolean" }, "last_password_change": { "type": "string", "format": "date-time", "nullable": true }, "login_sessions": { "type": "array", "items": { "$ref": "#/components/schemas/AdminLoginSession" } } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "AdminLoginSession": { "title": "Admin Login Session Object", "properties": { "id": { "type": "string", "example": "session_1" }, "ip_address": { "type": "string", "example": "192.168.1.1" }, "user_agent": { "type": "string", "example": "Mozilla/5.0 (Windows NT 10.0)" }, "location": { "type": "string", "example": "Current Location" }, "last_activity": { "type": "string", "format": "date-time" }, "is_current": { "type": "boolean", "example": true } }, "type": "object" }, "AdminProfileUpdate": { "title": "Admin Profile Update Request", "properties": { "name": { "type": "string", "example": "Updated Admin Name" }, "email": { "type": "string", "format": "email", "example": "updated_admin@example.com" }, "phone": { "type": "string", "example": "+1987654321", "nullable": true }, "position": { "type": "string", "example": "Senior System Admin", "nullable": true }, "department": { "type": "string", "example": "IT Operations", "nullable": true }, "bio": { "type": "string", "example": "Updated bio for admin user.", "nullable": true }, "timezone": { "type": "string", "example": "America/New_York", "nullable": true }, "language": { "type": "string", "example": "es", "nullable": true }, "theme": { "type": "string", "example": "dark", "nullable": true } }, "type": "object" }, "AdminPasswordChange": { "title": "Admin Password Change Request", "required": [ "current_password", "password", "password_confirmation" ], "properties": { "current_password": { "type": "string", "format": "password", "example": "OldPassword123!" }, "password": { "type": "string", "format": "password", "example": "NewSecurePassword456!" }, "password_confirmation": { "type": "string", "format": "password", "example": "NewSecurePassword456!" } }, "type": "object" }, "AdminNotificationPreferences": { "title": "Admin Notification Preferences Update Request", "properties": { "email_notifications": { "type": "boolean", "example": true }, "push_notifications": { "type": "boolean", "example": false }, "sms_notifications": { "type": "boolean", "example": true } }, "type": "object" }, "AdminToggleTwoFactor": { "title": "Admin Toggle Two-Factor Authentication Request", "required": [ "enabled", "password" ], "properties": { "enabled": { "type": "boolean", "example": true }, "password": { "type": "string", "format": "password", "example": "CurrentPassword123!" } }, "type": "object" }, "UserSession": { "title": "User Session Object", "properties": { "id": { "type": "integer", "example": 1 }, "user_id": { "type": "integer", "example": 1 }, "ip_address": { "type": "string", "example": "192.168.1.1" }, "user_agent": { "type": "string", "example": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "payload": { "type": "string", "example": "..." }, "last_activity": { "type": "integer", "example": 1678886400 }, "device_type": { "type": "string", "example": "desktop" }, "device_name": { "type": "string", "example": "My Desktop" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "ErrorResponse": { "title": "Error Response", "properties": { "message": { "type": "string", "example": "An error occurred." }, "error": { "type": "string", "example": "Detailed error message", "nullable": true } }, "type": "object" }, "ValidationErrors": { "title": "Validation Errors", "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object", "example": { "field": [ "The field is required." ] } } }, "type": "object" }, "Attendance": { "title": "Attendance Object", "properties": { "id": { "type": "integer", "example": 1 }, "employee_id": { "type": "integer", "example": 101 }, "company_id": { "type": "integer", "example": 1 }, "branch_id": { "type": "integer", "example": 1 }, "date": { "type": "string", "format": "date", "example": "2025-08-01" }, "check_in_time": { "type": "string", "format": "date-time", "example": "2025-08-01T09:00:00Z" }, "check_out_time": { "type": "string", "format": "date-time", "example": "2025-08-01T17:00:00Z", "nullable": true }, "attendance_method": { "type": "string", "example": "punch" }, "check_in_ip": { "type": "string", "example": "192.168.1.100" }, "check_out_ip": { "type": "string", "example": "192.168.1.100", "nullable": true }, "check_in_latitude": { "type": "number", "format": "float", "example": 34.052235, "nullable": true }, "check_in_longitude": { "type": "number", "format": "float", "example": -118.243683, "nullable": true }, "check_out_latitude": { "type": "number", "format": "float", "example": 34.052235, "nullable": true }, "check_out_longitude": { "type": "number", "format": "float", "example": -118.243683, "nullable": true }, "total_hours": { "description": "Total minutes", "type": "integer", "example": 480, "nullable": true }, "working_hours": { "description": "Working minutes", "type": "integer", "example": 480, "nullable": true }, "break_hours": { "description": "Break minutes", "type": "integer", "example": 60, "nullable": true }, "overtime_hours": { "description": "Overtime minutes", "type": "integer", "example": 0, "nullable": true }, "status": { "type": "string", "example": "present" }, "is_synced": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "employee": { "$ref": "#/components/schemas/Employee" }, "company": { "$ref": "#/components/schemas/Company" }, "branch": { "$ref": "#/components/schemas/Branch" } }, "type": "object" }, "AttendanceMethod": { "title": "Attendance Method Object", "properties": { "id": { "type": "integer", "example": 1 }, "branch_id": { "type": "integer", "example": 1 }, "method": { "type": "string", "example": "face_recognition" }, "is_enabled": { "type": "boolean", "example": true }, "settings": { "type": "object", "nullable": true } }, "type": "object" }, "AttendancePolicy": { "title": "Attendance Policy Object", "properties": { "id": { "type": "integer", "example": 1 }, "company_id": { "type": "integer", "example": 1 }, "branch_id": { "type": "integer", "example": 1, "nullable": true }, "name": { "type": "string", "example": "Standard Policy" }, "working_hours": { "type": "object", "example": { "monday": { "start": "09:00", "end": "17:00" } } }, "late_threshold_minutes": { "type": "integer", "example": 15 }, "allow_overtime": { "type": "boolean", "example": true }, "is_active": { "type": "boolean", "example": true } }, "type": "object" }, "Employee": { "title": "Employee Object", "properties": { "id": { "type": "integer", "example": 101 }, "user_id": { "type": "integer", "example": 1 }, "tenant_id": { "type": "integer", "example": 1 }, "company_id": { "type": "integer", "example": 1 }, "branch_id": { "type": "integer", "example": 1 }, "role_id": { "type": "integer", "example": 2 }, "employee_id": { "type": "string", "example": "EMP001" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "phone": { "type": "string", "example": "+1234567890", "nullable": true }, "status": { "type": "string", "example": "active" }, "employment_type": { "type": "string", "example": "full_time" }, "hire_date": { "type": "string", "format": "date", "example": "2020-01-01" }, "is_tenant_admin": { "type": "boolean", "example": false }, "user": { "$ref": "#/components/schemas/User" } }, "type": "object" }, "Company": { "title": "Company Object", "properties": { "id": { "type": "integer", "example": 1 }, "tenant_id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Acme Corp" }, "slug": { "type": "string", "example": "acme-corp" }, "is_active": { "type": "boolean", "example": true }, "settings": { "type": "object" } }, "type": "object" }, "Branch": { "title": "Branch Object", "properties": { "id": { "type": "integer", "example": 1 }, "tenant_id": { "type": "integer", "example": 1 }, "company_id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Main Office" }, "code": { "type": "string", "example": "MAIN" }, "is_active": { "type": "boolean", "example": true }, "is_headquarters": { "type": "boolean", "example": true }, "address": { "type": "object" } }, "type": "object" }, "User": { "title": "User Object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "john.doe@example.com" }, "user_type": { "type": "string", "example": "employee" }, "is_active": { "type": "boolean", "example": true }, "is_tenant_admin": { "type": "boolean", "example": true } }, "type": "object" }, "FeatureToggle": { "title": "Feature Toggle Object", "properties": { "id": { "type": "integer", "example": 1 }, "key": { "type": "string", "example": "feature_x_enabled" }, "name": { "type": "string", "example": "Feature X" }, "description": { "type": "string", "example": "Enables feature X for users.", "nullable": true }, "global_enabled": { "type": "boolean", "example": true }, "scope": { "type": "string", "enum": [ "global", "company", "branch" ], "example": "global" }, "company_id": { "type": "integer", "example": 1, "nullable": true }, "metadata": { "type": "object", "nullable": true }, "is_system_feature": { "type": "boolean", "example": false }, "priority": { "type": "integer", "example": 100 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "UserResponse": { "title": "User Response Object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "message": { "type": "string" } }, "type": "object" }, "UserListResponse": { "title": "User List Response Object", "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/Employee" } }, "pagination": { "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" }, "UserProfileResponse": { "title": "User Profile Response Object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "tenant": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "plan": { "type": "string" }, "status": { "type": "string" }, "features": { "type": "object" } }, "type": "object" } }, "type": "object" } }, "securitySchemes": { "bearerAuth": { "type": "http", "description": "Bearer token authentication", "name": "bearerAuth", "in": "header", "bearerFormat": "Passport", "scheme": "bearer" } } }, "tags": [ { "name": "Notification Configuration", "description": "API Endpoints for managing notification configurations" }, { "name": "Notification Templates", "description": "API Endpoints for managing notification templates" }, { "name": "Admin Profile", "description": "API Endpoints for managing admin user profiles" }, { "name": "Attendance", "description": "API Endpoints for managing attendance" }, { "name": "Branches", "description": "API Endpoints for managing branches" }, { "name": "Companies", "description": "API Endpoints for managing companies" }, { "name": "Dashboard", "description": "API Endpoints for retrieving dashboard statistics and data" }, { "name": "Employees", "description": "API Endpoints for managing employees" }, { "name": "Feature Toggles", "description": "API Endpoints for managing feature toggles" }, { "name": "Users", "description": "API Endpoints for managing users (employees)" }, { "name": "Authentication", "description": "Authentication" } ] }