{ "openapi": "3.0.0", "info": { "title": "Hasanat API Documentation", "description": "Comprehensive API documentation for Hasanat charity platform including authentication, donations, zakat calculations, and more.", "contact": { "email": "support@hasanat.com" }, "version": "1.0.0" }, "servers": [ { "url": "http://localhost:8000", "description": "Local Development Server" }, { "url": "https://api.hasanat.com", "description": "Production Server" } ], "paths": { "/api/admin/blogs": { "get": { "tags": [ "Admin - Blogs" ], "summary": "Get all blogs", "description": "Retrieve a paginated list of blogs with filtering and sorting options (Admin only)", "operationId": "getAdminBlogs", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "status", "in": "query", "description": "Filter by blog status", "required": false, "schema": { "type": "string", "enum": [ "draft", "published", "archived" ] } }, { "name": "search", "in": "query", "description": "Search in title and descriptions", "required": false, "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "description": "Field to sort by", "required": false, "schema": { "type": "string", "default": "created_at", "enum": [ "created_at", "display_order", "title_en" ] } }, { "name": "sort_order", "in": "query", "description": "Sort order", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Blogs retrieved successfully", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Blog" } }, "meta": { "type": "object" }, "links": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Admin - Blogs" ], "summary": "Create a new blog", "description": "Create a new blog post (Admin only)", "operationId": "storeBlog", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "title_en", "title_ar", "title_fr", "short_description_en", "short_description_ar", "short_description_fr", "full_description_en", "full_description_ar", "full_description_fr", "status" ], "properties": { "title_en": { "type": "string", "maxLength": 46, "example": "Blog Title in English" }, "title_ar": { "type": "string", "maxLength": 46, "example": "عنوان المدونة بالعربية" }, "title_fr": { "type": "string", "maxLength": 46, "example": "Titre du blog en français" }, "short_description_en": { "type": "string", "maxLength": 115, "example": "Short description in English" }, "short_description_ar": { "type": "string", "maxLength": 115, "example": "وصف قصير بالعربية" }, "short_description_fr": { "type": "string", "maxLength": 115, "example": "Courte description en français" }, "full_description_en": { "type": "string", "example": "Full description in English" }, "full_description_ar": { "type": "string", "example": "وصف كامل بالعربية" }, "full_description_fr": { "type": "string", "example": "Description complète en français" }, "image": { "type": "string", "format": "binary" }, "display_order": { "type": "integer", "example": 1 }, "status": { "type": "string", "enum": [ "draft", "published", "archived" ], "example": "draft" } }, "type": "object" } } } }, "responses": { "201": { "description": "Blog created successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Blog created successfully" }, "data": { "$ref": "#/components/schemas/Blog" } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/blogs/recent": { "get": { "tags": [ "Admin - Blogs" ], "summary": "Get recent published blogs", "description": "Retrieve recent published blogs (Admin only)", "operationId": "getAdminRecentBlogs", "parameters": [ { "name": "limit", "in": "query", "description": "Number of blogs to retrieve", "required": false, "schema": { "type": "integer", "default": 3, "maximum": 50, "minimum": 1 } } ], "responses": { "200": { "description": "Recent blogs retrieved successfully", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Blog" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/blogs/{id}": { "get": { "tags": [ "Admin - Blogs" ], "summary": "Get a specific blog", "description": "Retrieve a specific blog by ID for editing (Admin only)", "operationId": "showBlog", "parameters": [ { "name": "id", "in": "path", "description": "Blog ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Blog retrieved successfully", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Blog" } }, "type": "object" } } } }, "404": { "description": "Blog not found" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Admin - Blogs" ], "summary": "Update a blog", "description": "Update an existing blog post (Admin only). Use POST with _method=PUT for file uploads.", "operationId": "updateBlog", "parameters": [ { "name": "id", "in": "path", "description": "Blog ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "multipart/form-data": { "schema": { "properties": { "_method": { "type": "string", "enum": [ "PUT" ], "example": "PUT" }, "title_en": { "type": "string", "maxLength": 46 }, "title_ar": { "type": "string", "maxLength": 46 }, "title_fr": { "type": "string", "maxLength": 46 }, "short_description_en": { "type": "string", "maxLength": 115 }, "short_description_ar": { "type": "string", "maxLength": 115 }, "short_description_fr": { "type": "string", "maxLength": 115 }, "full_description_en": { "type": "string" }, "full_description_ar": { "type": "string" }, "full_description_fr": { "type": "string" }, "image": { "type": "string", "format": "binary" }, "display_order": { "type": "integer" }, "status": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "remove_image": { "type": "boolean", "example": false } }, "type": "object" } } } }, "responses": { "200": { "description": "Blog updated successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Blog updated successfully" }, "data": { "$ref": "#/components/schemas/Blog" } }, "type": "object" } } } }, "404": { "description": "Blog not found" }, "422": { "description": "Validation error" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Admin - Blogs" ], "summary": "Delete a blog", "description": "Soft delete a blog post (Admin only)", "operationId": "deleteBlog", "parameters": [ { "name": "id", "in": "path", "description": "Blog ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Blog deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Blog deleted successfully" }, "data": { "properties": { "id": { "type": "integer" }, "deleted_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Blog not found" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/blogs/stats": { "get": { "tags": [ "Admin - Blogs" ], "summary": "Get blog statistics", "description": "Retrieve aggregated blog statistics including counts by status and recent blogs. Uses database aggregations for optimal performance. Results are cached for 60 seconds. Admin access required.", "operationId": "getBlogStats", "parameters": [ { "name": "locale", "in": "query", "description": "Language locale (en, ar, or fr). Accepted for API consistency but not used in calculations as statistics are language-agnostic.", "required": false, "schema": { "type": "string", "default": "en", "enum": [ "en", "ar", "fr" ] } } ], "responses": { "200": { "description": "Statistics retrieved successfully", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "total": { "description": "Total number of blogs", "type": "integer", "example": 150 }, "published": { "description": "Number of published blogs", "type": "integer", "example": 80 }, "draft": { "description": "Number of draft blogs", "type": "integer", "example": 50 }, "archived": { "description": "Number of archived blogs", "type": "integer", "example": 20 }, "recent": { "description": "Number of blogs created in the last 7 days", "type": "integer", "example": 12 } }, "type": "object" }, "meta": { "properties": { "cached": { "description": "Whether the result was served from cache", "type": "boolean", "example": true }, "cache_ttl": { "description": "Cache TTL in seconds", "type": "integer", "example": 60 }, "timestamp": { "description": "Response timestamp", "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Forbidden - Admin access required", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthorized." }, "error": { "type": "string", "example": "You do not have permission to access this resource." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/categories": { "get": { "tags": [ "Admin - Categories" ], "summary": "Get all categories", "description": "Retrieve a list of all categories (Admin only)", "operationId": "getCategories", "responses": { "200": { "description": "Categories retrieved successfully", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Admin - Categories" ], "summary": "Create a new category", "description": "Create a new category (Admin only)", "operationId": "storeCategory", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name_en", "name_ar" ], "properties": { "name_en": { "type": "string", "example": "Education" }, "name_ar": { "type": "string", "example": "تعليم" }, "name_fr": { "type": "string", "example": "Éducation", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Category created successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Category created successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/categories/{id}": { "get": { "tags": [ "Admin - Categories" ], "summary": "Get a specific category", "description": "Retrieve a specific category by ID (Admin only)", "operationId": "showCategory", "parameters": [ { "name": "id", "in": "path", "description": "Category ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Category retrieved successfully", "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Category not found" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Admin - Categories" ], "summary": "Update a category", "description": "Update an existing category (Admin only)", "operationId": "updateCategory", "parameters": [ { "name": "id", "in": "path", "description": "Category ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name_en", "name_ar" ], "properties": { "name_en": { "type": "string", "example": "Education" }, "name_ar": { "type": "string", "example": "تعليم" }, "name_fr": { "type": "string", "example": "Éducation", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Category updated successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Category updated successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Category not found" }, "422": { "description": "Validation error" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Admin - Categories" ], "summary": "Delete a category", "description": "Delete an existing category (Admin only). Categories with associated projects cannot be deleted.", "operationId": "deleteCategory", "parameters": [ { "name": "id", "in": "path", "description": "Category ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Category deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Category deleted successfully" } }, "type": "object" } } } }, "404": { "description": "Category not found" }, "409": { "description": "Conflict - Category has associated projects" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/admins": { "get": { "tags": [ "Admin - Admins" ], "summary": "Get all admins", "description": "Retrieve a paginated list of all admins with optional search (Admin only)", "operationId": "getAdmins", "parameters": [ { "name": "search", "in": "query", "description": "Search by name or email", "required": false, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Admins retrieved successfully", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "type": "object" } }, "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Admin - Admins" ], "summary": "Create a new admin", "description": "Create a new admin (Admin only)", "operationId": "storeAdmin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "password", "role", "status" ], "properties": { "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "john@example.com" }, "password": { "type": "string", "format": "password", "minLength": 8, "example": "password123" }, "phone": { "type": "string", "example": "+966501234567", "nullable": true }, "role": { "type": "string", "enum": [ "super_admin", "admin", "moderator" ], "example": "admin" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "example": "active" } }, "type": "object" } } } }, "responses": { "201": { "description": "Admin created successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Admin created successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/admins/{id}": { "get": { "tags": [ "Admin - Admins" ], "summary": "Get a specific admin", "description": "Retrieve a specific admin by ID (Admin only)", "operationId": "showAdmin", "parameters": [ { "name": "id", "in": "path", "description": "Admin ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Admin retrieved successfully", "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Admin not found" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Admin - Admins" ], "summary": "Update an admin", "description": "Update an existing admin (Admin only)", "operationId": "updateAdmin", "parameters": [ { "name": "id", "in": "path", "description": "Admin ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "role", "status" ], "properties": { "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "john@example.com" }, "password": { "type": "string", "format": "password", "minLength": 8, "example": "newpassword123", "nullable": true }, "phone": { "type": "string", "example": "+966501234567", "nullable": true }, "role": { "type": "string", "enum": [ "super_admin", "admin", "moderator" ], "example": "admin" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "example": "active" } }, "type": "object" } } } }, "responses": { "200": { "description": "Admin updated successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Admin updated successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Admin not found" }, "422": { "description": "Validation error" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Admin - Admins" ], "summary": "Delete an admin", "description": "Delete an existing admin (Admin only). Admins with associated projects cannot be deleted.", "operationId": "deleteAdmin", "parameters": [ { "name": "id", "in": "path", "description": "Admin ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Admin deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Admin deleted successfully" } }, "type": "object" } } } }, "404": { "description": "Admin not found" }, "409": { "description": "Conflict - Admin has associated projects" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/dashboard/donation-trends": { "get": { "tags": [ "Admin - Dashboard" ], "summary": "Get donation trends by frequency", "description": "Retrieve donation statistics grouped by frequency type (one-off, weekly, monthly, fortnightly). Results are cached for 5 minutes.", "operationId": "getDonationTrends", "responses": { "200": { "description": "Donation trends retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "trends": { "type": "array", "items": { "properties": { "type": { "type": "string", "example": "one_off" }, "amount": { "type": "number", "example": 400 }, "percentage": { "type": "number", "example": 25 }, "count": { "type": "integer", "example": 10 } }, "type": "object" } }, "total_amount": { "type": "number", "example": 1600 }, "total_count": { "type": "integer", "example": 40 }, "currency": { "properties": { "code": { "type": "string", "example": "USD" }, "symbol": { "type": "string", "example": "$" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/dashboard/recent-activities": { "get": { "tags": [ "Admin - Dashboard" ], "summary": "Get recent activities", "description": "Retrieve recent activities including donations, new donors, and project updates. Results are cached for 2 minutes.", "operationId": "getRecentActivities", "parameters": [ { "name": "limit", "in": "query", "description": "Number of activities to retrieve", "required": false, "schema": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1 } } ], "responses": { "200": { "description": "Recent activities retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "donation-123" }, "type": { "type": "string", "example": "donation" }, "title": { "type": "string", "example": "Donation from Ahmed Youssef" }, "description": { "type": "string", "example": "$150" }, "amount": { "type": "number", "example": 150 }, "currency": { "type": "object" }, "donor_name": { "type": "string", "example": "Ahmed Youssef" }, "created_at": { "type": "string", "format": "date-time" }, "time_ago": { "type": "string", "example": "10 minutes ago" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/donations/manual": { "post": { "tags": [ "Admin - Donations" ], "summary": "Create manual donation (Admin only)", "description": "Create a completed donation record for manual payments (cash, check, bank transfer)", "operationId": "createManualDonation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "project_id", "amount", "currency_id", "donor_name", "donor_email" ], "properties": { "project_id": { "type": "integer", "example": 1 }, "amount": { "type": "number", "format": "float", "example": 100 }, "currency_id": { "type": "integer", "example": 1 }, "donor_name": { "type": "string", "example": "John Doe" }, "donor_email": { "type": "string", "format": "email", "example": "john@example.com" }, "donor_phone": { "type": "string", "nullable": true }, "is_anonymous": { "type": "boolean", "example": false }, "is_gift": { "type": "boolean", "example": false }, "message": { "type": "string", "nullable": true }, "payment_method": { "type": "string", "enum": [ "manual", "cash", "bank_transfer" ], "example": "manual" }, "user_id": { "description": "Link to existing user account", "type": "integer", "nullable": true }, "admin_notes": { "type": "string", "nullable": true }, "payment_date": { "type": "string", "format": "date", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Manual donation created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Manual donation created successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "403": { "description": "Forbidden - Admin access required" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/donations/{id}/complete-manual": { "post": { "tags": [ "Admin - Donations" ], "summary": "Complete manual donation (Admin only)", "description": "Mark a pending donation as completed and generate receipt", "operationId": "completeManualDonation", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Donation completed successfully" }, "404": { "description": "Donation not found" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/homepage": { "get": { "tags": [ "Admin - Homepage Sections" ], "summary": "Get all homepage sections", "description": "Retrieve a list of all homepage sections with their projects (Admin only)", "operationId": "getAdminHomepageSections", "responses": { "200": { "description": "Homepage sections retrieved successfully", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/homepage/{sectionKey}": { "get": { "tags": [ "Admin - Homepage Sections" ], "summary": "Get a specific homepage section", "description": "Retrieve a specific homepage section by key with its projects (Admin only)", "operationId": "showHomepageSection", "parameters": [ { "name": "sectionKey", "in": "path", "description": "Homepage section key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Homepage section retrieved successfully", "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Homepage section not found" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Admin - Homepage Sections" ], "summary": "Update a homepage section", "description": "Update an existing homepage section with projects (Admin only)", "operationId": "updateHomepageSection", "parameters": [ { "name": "sectionKey", "in": "path", "description": "Homepage section key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "project_id": { "description": "Project ID (for hero section)", "type": "integer" }, "projects": { "description": "Array of projects (for weekly/project_story sections)", "type": "array", "items": { "type": "object" } }, "settings": { "description": "Section settings (JSON)", "type": "object", "nullable": true }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Homepage section updated successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Homepage section updated successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Homepage section not found" }, "422": { "description": "Validation error" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/homepage/{sectionKey}/toggle-visibility": { "post": { "tags": [ "Admin - Homepage Sections" ], "summary": "Toggle homepage section visibility", "description": "Toggle the is_active status of a homepage section (Admin only)", "operationId": "toggleHomepageSectionVisibility", "parameters": [ { "name": "sectionKey", "in": "path", "description": "Homepage section key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Homepage section visibility toggled successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Homepage section visibility toggled successfully" }, "data": { "properties": { "section_key": { "type": "string" }, "is_active": { "type": "boolean" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Homepage section not found" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/projects/{id}": { "get": { "tags": [ "Admin - Projects" ], "summary": "Get a project for editing", "description": "Retrieve a single project with all fields for editing (Admin only)", "operationId": "getAdminProject", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Project retrieved successfully", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Project" } }, "type": "object" } } } }, "404": { "description": "Project not found" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Admin - Projects" ], "summary": "Update a project", "description": "Update an existing charity project (Admin only). Use POST with _method=PUT for file uploads.", "operationId": "updateProject", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "multipart/form-data": { "schema": { "properties": { "_method": { "type": "string", "enum": [ "PUT" ], "example": "PUT" }, "title_en": { "type": "string", "example": "Updated Title" }, "title_ar": { "type": "string", "example": "عنوان محدث" }, "description_en": { "type": "string" }, "description_ar": { "type": "string" }, "short_description_en": { "type": "string" }, "short_description_ar": { "type": "string" }, "category_id": { "description": "Category ID from categories table", "type": "integer" }, "goal_amount": { "type": "number", "format": "float" }, "current_amount": { "type": "number", "format": "float" }, "currency_id": { "type": "integer" }, "image": { "type": "string", "format": "binary" }, "remove_image": { "type": "boolean", "example": false }, "video_url": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "status": { "type": "string", "enum": [ "draft", "active", "completed", "paused", "cancelled" ] }, "is_featured": { "type": "boolean" }, "allow_anonymous": { "type": "boolean" }, "donors_count": { "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Project updated successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Project updated successfully" }, "data": { "$ref": "#/components/schemas/Project" } }, "type": "object" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Project not found" }, "error": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Forbidden - Admin access required" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Admin - Projects" ], "summary": "Delete a project", "description": "Soft delete a charity project (Admin only)", "operationId": "deleteProject", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Project deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Project deleted successfully" }, "data": { "properties": { "id": { "type": "integer" }, "deleted_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Project not found" }, "error": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/projects": { "post": { "tags": [ "Admin - Projects" ], "summary": "Create a new project", "description": "Create a new charity project (Admin only)", "operationId": "storeProject", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "title_en", "title_ar", "description_en", "description_ar", "goal_amount" ], "properties": { "title_en": { "type": "string", "example": "Build a School in Gaza" }, "title_ar": { "type": "string", "example": "بناء مدرسة في غزة" }, "description_en": { "type": "string", "example": "Help us build a school..." }, "description_ar": { "type": "string", "example": "ساعدنا في بناء مدرسة..." }, "short_description_en": { "type": "string", "example": "Build a school" }, "short_description_ar": { "type": "string", "example": "بناء مدرسة" }, "category_id": { "description": "Category ID from categories table", "type": "integer", "example": 1 }, "goal_amount": { "type": "number", "format": "float", "example": 50000 }, "currency_id": { "type": "integer", "example": 1 }, "image": { "type": "string", "format": "binary" }, "video_url": { "type": "string", "example": "https://youtube.com/watch?v=..." }, "start_date": { "type": "string", "format": "date", "example": "2024-01-01" }, "end_date": { "type": "string", "format": "date", "example": "2024-12-31" }, "status": { "type": "string", "enum": [ "draft", "active", "completed", "paused", "cancelled" ], "example": "draft" }, "is_featured": { "type": "boolean", "example": false }, "allow_anonymous": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Project created successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Project created successfully" }, "data": { "$ref": "#/components/schemas/Project" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Forbidden - Admin access required", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthorized." }, "error": { "type": "string", "example": "You do not have permission to access this resource." } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/regions": { "get": { "tags": [ "Admin - Regions" ], "summary": "Get all regions", "description": "Retrieve a list of all regions (Admin only)", "operationId": "getRegions", "responses": { "200": { "description": "Regions retrieved successfully", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Admin - Regions" ], "summary": "Create a new region", "description": "Create a new region (Admin only)", "operationId": "storeRegion", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name_en", "name_ar" ], "properties": { "name_en": { "type": "string", "example": "Cairo" }, "name_ar": { "type": "string", "example": "القاهرة" }, "name_fr": { "type": "string", "example": "Le Caire", "nullable": true }, "code": { "type": "string", "example": "CAI", "nullable": true }, "type": { "type": "string", "enum": [ "country", "state", "city", "camp" ], "example": "city", "nullable": true }, "parent_id": { "type": "integer", "example": 1, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Region created successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Region created successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/regions/{id}": { "get": { "tags": [ "Admin - Regions" ], "summary": "Get a specific region", "description": "Retrieve a specific region by ID (Admin only)", "operationId": "showRegion", "parameters": [ { "name": "id", "in": "path", "description": "Region ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Region retrieved successfully", "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Region not found" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Admin - Regions" ], "summary": "Update a region", "description": "Update an existing region (Admin only)", "operationId": "updateRegion", "parameters": [ { "name": "id", "in": "path", "description": "Region ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name_en", "name_ar" ], "properties": { "name_en": { "type": "string", "example": "Cairo" }, "name_ar": { "type": "string", "example": "القاهرة" }, "name_fr": { "type": "string", "example": "Le Caire", "nullable": true }, "code": { "type": "string", "example": "CAI", "nullable": true }, "type": { "type": "string", "enum": [ "country", "state", "city", "camp" ], "example": "city", "nullable": true }, "parent_id": { "type": "integer", "example": 1, "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Region updated successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Region updated successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Region not found" }, "422": { "description": "Validation error" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Admin - Regions" ], "summary": "Delete a region", "description": "Delete an existing region (Admin only). Regions with associated projects or child regions cannot be deleted.", "operationId": "deleteRegion", "parameters": [ { "name": "id", "in": "path", "description": "Region ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Region deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Region deleted successfully" } }, "type": "object" } } } }, "404": { "description": "Region not found" }, "409": { "description": "Conflict - Region has associated projects or child regions" }, "403": { "description": "Forbidden - Admin access required" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/reports/overview-stats": { "get": { "tags": [ "Admin - Reports" ], "summary": "Get overview statistics", "description": "Retrieve overview statistics including total donations, total donors, recurring donors, projects completed, and urgent projects. Results are cached for 60 seconds.", "operationId": "getOverviewStats", "parameters": [ { "name": "from_date", "in": "query", "description": "Start date filter (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "description": "End date filter (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Overview statistics retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "total_donations": { "type": "number", "example": 125000 }, "total_donors": { "type": "integer", "example": 150 }, "recurring_donors": { "type": "integer", "example": 45 }, "projects_completed": { "type": "integer", "example": 12 }, "urgent_projects": { "type": "integer", "example": 5 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Admin access required" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/reports/donation-progress": { "get": { "tags": [ "Admin - Reports" ], "summary": "Get monthly donation progress", "description": "Retrieve monthly donation progress data for line chart visualization. Results are cached for 60 seconds.", "operationId": "getDonationProgress", "parameters": [ { "name": "from_date", "in": "query", "description": "Start date filter (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "description": "End date filter (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Donation progress data retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "months": { "type": "array", "items": { "type": "string", "example": "2024-01" } }, "amounts": { "type": "array", "items": { "type": "number", "example": 15000 } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Admin access required" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/reports/project-progress": { "get": { "tags": [ "Admin - Reports" ], "summary": "Get project progress data", "description": "Retrieve project progress data for stacked bar chart visualization. Results are cached for 60 seconds.", "operationId": "getProjectProgress", "parameters": [ { "name": "from_date", "in": "query", "description": "Start date filter (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "description": "End date filter (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Project progress data retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "projects": { "type": "array", "items": { "type": "string", "example": "Project Name" } }, "current_amounts": { "type": "array", "items": { "type": "number", "example": 25000 } }, "goal_amounts": { "type": "array", "items": { "type": "number", "example": 50000 } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Admin access required" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/reports/donors": { "get": { "tags": [ "Admin - Reports" ], "summary": "Get paginated donors list", "description": "Retrieve a paginated list of donors with optional filters", "operationId": "getDonors", "parameters": [ { "name": "from_date", "in": "query", "description": "Start date filter (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "description": "End date filter (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "search", "in": "query", "description": "Search by name or email", "required": false, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Donors retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "meta": { "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Admin access required" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/reports/donors-stats": { "get": { "tags": [ "Admin - Reports" ], "summary": "Get donor statistics", "description": "Retrieve donor statistics. Results are cached for 60 seconds.", "operationId": "getDonorsStats", "parameters": [ { "name": "from_date", "in": "query", "description": "Start date filter (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "description": "End date filter (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Donor statistics retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "total_donors": { "type": "integer", "example": 150 }, "new_donors": { "type": "integer", "example": 25 }, "recurring_donors": { "type": "integer", "example": 45 }, "average_donation_amount": { "type": "number", "example": 250 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Admin access required" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/reports/donations": { "get": { "tags": [ "Admin - Reports" ], "summary": "Get paginated donations list", "description": "Retrieve a paginated list of donations with optional filters", "operationId": "getAdminReportsDonations", "parameters": [ { "name": "from_date", "in": "query", "description": "Start date filter (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "description": "End date filter (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "pending", "completed", "failed", "refunded", "cancelled" ] } }, { "name": "search", "in": "query", "description": "Search term for donor name, donor email, user name, or user email (case-insensitive)", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Donations retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Donation" } }, "meta": { "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Admin access required" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/reports/donations-stats": { "get": { "tags": [ "Admin - Reports" ], "summary": "Get donation statistics", "description": "Retrieve donation statistics. Results are cached for 60 seconds.", "operationId": "getDonationsStats", "parameters": [ { "name": "from_date", "in": "query", "description": "Start date filter (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "description": "End date filter (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Donation statistics retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "total_donations": { "type": "integer", "example": 500 }, "total_amount": { "type": "number", "example": 125000 }, "completed_donations": { "type": "integer", "example": 450 }, "pending_donations": { "type": "integer", "example": 30 }, "failed_donations": { "type": "integer", "example": 20 }, "cancelled_donations": { "type": "integer", "example": 5 }, "active_donations": { "type": "integer", "example": 120 }, "paused_donations": { "type": "integer", "example": 15 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Admin access required" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/reports/gift-donations": { "get": { "tags": [ "Admin - Reports" ], "summary": "Get paginated gift donations list", "description": "Retrieve a paginated list of gift donations with optional filters", "operationId": "getGiftDonations", "parameters": [ { "name": "from_date", "in": "query", "description": "Start date filter (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "description": "End date filter (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "pending", "completed", "failed", "refunded", "cancelled" ] } }, { "name": "search", "in": "query", "description": "Search term for donor name, donor email, gift recipient name, gift recipient email, user name, or user email (case-insensitive)", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "cause", "in": "query", "description": "Filter by cause/category ID", "required": false, "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Gift donations retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Donation" } }, "meta": { "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Admin access required" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/reports/gift-donations-stats": { "get": { "tags": [ "Admin - Reports" ], "summary": "Get gift donation statistics", "description": "Retrieve gift donation statistics. Results are cached for 60 seconds.", "operationId": "getGiftDonationsStats", "parameters": [ { "name": "from_date", "in": "query", "description": "Start date filter (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "description": "End date filter (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Gift donation statistics retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "total_gift_donations": { "type": "integer", "example": 150 }, "total_amount": { "type": "number", "example": 37500 }, "completed_gift_donations": { "type": "integer", "example": 140 }, "average_gift_amount": { "type": "number", "example": 250 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Admin access required" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/reports/payments": { "get": { "tags": [ "Admin - Reports" ], "summary": "Get paginated payments list", "description": "Retrieve a paginated list of payments (transactions) with optional filters", "operationId": "getPayments", "parameters": [ { "name": "from_date", "in": "query", "description": "Start date filter (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "description": "End date filter (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "refunded" ] } }, { "name": "payment_gateway", "in": "query", "description": "Filter by payment gateway", "required": false, "schema": { "type": "string", "enum": [ "paypal", "stripe", "bank", "cash" ] } }, { "name": "search", "in": "query", "description": "Search term for transaction ID, payer email, donor name, donor email, user name, or user email (case-insensitive)", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Payments retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object" } }, "meta": { "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Admin access required" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/reports/payments-stats": { "get": { "tags": [ "Admin - Reports" ], "summary": "Get payment statistics", "description": "Retrieve payment statistics. Results are cached for 60 seconds.", "operationId": "getPaymentsStats", "parameters": [ { "name": "from_date", "in": "query", "description": "Start date filter (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "description": "End date filter (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Payment statistics retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "total_payments": { "type": "integer", "example": 500 }, "total_amount": { "type": "number", "example": 125000 }, "total_fees": { "type": "number", "example": 3750 }, "net_amount": { "type": "number", "example": 121250 }, "completed_payments": { "type": "integer", "example": 450 }, "failed_payments": { "type": "integer", "example": 20 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Admin access required" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/cart": { "get": { "tags": [ "Cart" ], "summary": "Get cart items", "description": "Retrieve all items in the cart (supports session-based for guests, user-based for authenticated)", "operationId": "getCart", "responses": { "200": { "description": "Cart items retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Cart items retrieved successfully" }, "data": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } } } }, "delete": { "tags": [ "Cart" ], "summary": "Clear entire cart", "description": "Remove all items from the cart", "operationId": "clearCart", "responses": { "200": { "description": "Cart cleared successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Cart cleared successfully" }, "items_deleted": { "type": "integer", "example": 3 } }, "type": "object" } } } } } } }, "/api/cart/add": { "post": { "tags": [ "Cart" ], "summary": "Add item to cart", "description": "Add a donation item to the cart (supports all three donation types: regular, anonymous, gift)", "operationId": "addCartItem", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "project_id", "currency_id", "amount", "donation_type" ], "properties": { "project_id": { "type": "integer", "example": 1 }, "currency_id": { "type": "integer", "example": 1 }, "amount": { "type": "number", "format": "float", "example": 100 }, "frequency": { "type": "string", "enum": [ "one-time", "monthly", "quarterly", "yearly" ], "example": "one-time" }, "donation_type": { "type": "string", "enum": [ "regular", "anonymous", "gift" ], "example": "regular" }, "is_anonymous": { "type": "boolean", "example": false }, "is_gift": { "type": "boolean", "example": false }, "gift_recipient_name": { "type": "string", "example": "John Doe" }, "gift_recipient_email": { "type": "string", "format": "email", "example": "john@example.com" }, "gift_message": { "type": "string", "example": "Happy Birthday!" } }, "type": "object" } } } }, "responses": { "201": { "description": "Item added to cart successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Item added to cart successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error" } } } }, "/api/cart/{itemId}": { "put": { "tags": [ "Cart" ], "summary": "Update cart item", "description": "Update a cart item (amount, frequency, recipient info for gifts)", "operationId": "updateCartItem", "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "amount": { "type": "number", "format": "float", "example": 150 }, "frequency": { "type": "string", "enum": [ "one-time", "monthly", "quarterly", "yearly" ] }, "donation_type": { "type": "string", "enum": [ "regular", "anonymous", "gift" ] }, "gift_recipient_name": { "type": "string" }, "gift_recipient_email": { "type": "string", "format": "email" }, "gift_message": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Cart item updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Cart item updated successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Cart item not found" }, "422": { "description": "Validation error" } } }, "delete": { "tags": [ "Cart" ], "summary": "Remove item from cart", "description": "Remove a specific item from the cart", "operationId": "removeCartItem", "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Item removed from cart successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Item removed from cart successfully" } }, "type": "object" } } } }, "404": { "description": "Cart item not found" } } } }, "/api/cart/checkout": { "post": { "tags": [ "Cart" ], "summary": "Initiate checkout", "description": "Create a checkout session from cart items (creates pending donations, returns checkout session ID)", "operationId": "initiateCheckout", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "item_ids" ], "properties": { "item_ids": { "type": "array", "items": { "type": "integer" }, "example": [ 1, 2, 3 ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Checkout session created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Checkout session created successfully" }, "checkout_session_id": { "type": "string", "example": "checkout_abc123..." } }, "type": "object" } } } }, "422": { "description": "Validation error" } } } }, "/api/cart/summary": { "get": { "tags": [ "Cart" ], "summary": "Get cart summary", "description": "Get cart summary with totals and item count", "operationId": "getCartSummary", "responses": { "200": { "description": "Cart summary retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Cart summary retrieved successfully" }, "data": { "properties": { "item_count": { "type": "integer", "example": 3 }, "total_amount_usd": { "type": "number", "example": 250 }, "items_by_currency": { "type": "object" }, "items_by_project": { "type": "object" } }, "type": "object" } }, "type": "object" } } } } } } }, "/api/checkout/{sessionId}": { "get": { "tags": [ "Checkout" ], "summary": "Get checkout session details", "description": "Retrieve details of a checkout session", "operationId": "getCheckoutSession", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Checkout session retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Checkout session retrieved successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Checkout session not found" } } } }, "/api/checkout/{sessionId}/donor-info": { "post": { "tags": [ "Checkout" ], "summary": "Submit donor information", "description": "Submit donor information for anonymous/guest donations", "operationId": "submitDonorInfo", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email" ], "properties": { "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "john@example.com" }, "business_name": { "type": "string", "example": "Acme Corp" }, "phone_number": { "type": "string", "example": "1234567890" }, "country_code": { "type": "string", "example": "+1" } }, "type": "object" } } } }, "responses": { "200": { "description": "Donor information submitted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Donor information submitted successfully" } }, "type": "object" } } } }, "404": { "description": "Checkout session not found" }, "422": { "description": "Validation error" } } } }, "/api/checkout/{sessionId}/complete": { "post": { "tags": [ "Checkout" ], "summary": "Complete checkout", "description": "Complete checkout (send receipts, notifications)", "operationId": "completeCheckout", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Checkout completed successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Checkout completed successfully" } }, "type": "object" } } } }, "404": { "description": "Checkout session not found" } } } }, "/api/donations": { "get": { "tags": [ "Donations" ], "summary": "Get user's donation history", "description": "Retrieve a paginated list of donations made by the authenticated user with summary statistics", "operationId": "getDonations", "parameters": [ { "name": "status", "in": "query", "description": "Filter by donation status (pending, completed, failed, cancelled)", "required": false, "schema": { "type": "string", "enum": [ "pending", "completed", "failed", "cancelled" ] } }, { "name": "from_date", "in": "query", "description": "Filter donations from this date (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "description": "Filter donations until this date (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "per_page", "in": "query", "description": "Number of items per page (default: 10, max: 100)", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1 } }, { "name": "sort_by", "in": "query", "description": "Field to sort by (default: created_at)", "required": false, "schema": { "type": "string", "enum": [ "created_at", "amount", "status" ] } }, { "name": "sort_order", "in": "query", "description": "Sort order (default: desc)", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Donation history retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Donation history retrieved successfully" }, "data": { "type": "array", "items": { "type": "object" } }, "summary": { "properties": { "total_donations": { "type": "integer", "example": 25 }, "total_amount_usd": { "type": "number", "example": 1250.5 }, "average_donation_usd": { "type": "number", "example": 50.02 }, "by_status": { "properties": { "completed": { "properties": { "count": { "type": "integer", "example": 20 }, "total_amount_usd": { "type": "number", "example": 1100 } }, "type": "object" }, "pending": { "properties": { "count": { "type": "integer", "example": 3 }, "total_amount_usd": { "type": "number", "example": 100.5 } }, "type": "object" }, "failed": { "properties": { "count": { "type": "integer", "example": 1 }, "total_amount_usd": { "type": "number", "example": 25 } }, "type": "object" }, "cancelled": { "properties": { "count": { "type": "integer", "example": 1 }, "total_amount_usd": { "type": "number", "example": 25 } }, "type": "object" } }, "type": "object" }, "recurring_donations_count": { "type": "integer", "example": 5 }, "anonymous_donations_count": { "type": "integer", "example": 3 }, "first_donation_date": { "type": "string", "format": "date-time", "nullable": true }, "last_donation_date": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "pagination": { "properties": { "total": { "type": "integer", "example": 25 }, "count": { "type": "integer", "example": 10 }, "per_page": { "type": "integer", "example": 10 }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 3 }, "from": { "type": "integer", "example": 1 }, "to": { "type": "integer", "example": 10 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Donations" ], "summary": "Create a new donation", "description": "Create a new donation for a project. The donation will be created with 'pending' status and requires payment processing.", "operationId": "createDonation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "project_id", "amount", "currency_id" ], "properties": { "project_id": { "description": "ID of the project to donate to", "type": "integer", "example": 1 }, "amount": { "description": "Donation amount (minimum: 1)", "type": "number", "format": "float", "example": 100 }, "currency_id": { "description": "ID of the currency", "type": "integer", "example": 1 }, "is_anonymous": { "description": "Whether the donation should be anonymous", "type": "boolean", "example": false }, "message": { "description": "Optional message (max 500 characters)", "type": "string", "example": "In memory of my grandmother" } }, "type": "object" } } } }, "responses": { "201": { "description": "Donation created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Donation created successfully. Please proceed with payment." }, "data": { "properties": { "id": { "type": "integer", "example": 1 }, "amount": { "type": "number", "example": 100 }, "amount_in_usd": { "type": "number", "example": 100 }, "status": { "type": "string", "example": "pending" }, "payment_method": { "description": "Will be set after payment gateway processes the payment", "type": "string", "example": null, "nullable": true }, "is_anonymous": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "In memory of my grandmother" }, "project": { "properties": { "id": { "type": "integer", "example": 1 }, "title": { "type": "string", "example": "Clean Water Initiative" }, "status": { "type": "string", "example": "active" } }, "type": "object" }, "transaction": { "properties": { "id": { "type": "integer", "example": 1 }, "transaction_id": { "type": "string", "example": "TXN-20251028-ABC123" }, "payment_gateway": { "description": "Will be set after payment is processed", "type": "string", "example": null, "nullable": true }, "status": { "type": "string", "example": "pending" } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to create donation" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/donations/{id}": { "get": { "tags": [ "Donations" ], "summary": "Get a specific donation", "description": "Retrieve details of a specific donation made by the authenticated user", "operationId": "getDonation", "parameters": [ { "name": "id", "in": "path", "description": "Donation ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Donation details retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Donation details retrieved successfully" }, "data": { "properties": { "id": { "type": "integer", "example": 1 }, "amount": { "type": "number", "example": 100 }, "status": { "type": "string", "example": "pending" }, "project": { "type": "object" }, "transaction": { "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Donation not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Donation not found or you do not have permission to view it" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/donations/export": { "get": { "tags": [ "Donations" ], "summary": "Export donations to CSV/Excel", "description": "Export user's donation history to CSV or Excel file with filtering support", "operationId": "exportDonations", "parameters": [ { "name": "status", "in": "query", "description": "Filter by donation status (pending, completed, failed, cancelled)", "required": false, "schema": { "type": "string", "enum": [ "pending", "completed", "failed", "cancelled" ] } }, { "name": "from_date", "in": "query", "description": "Filter donations from this date (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "description": "Filter donations until this date (Y-m-d format)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "format", "in": "query", "description": "Export format (csv or excel)", "required": false, "schema": { "type": "string", "default": "csv", "enum": [ "csv", "excel" ] } } ], "responses": { "200": { "description": "Export file generated successfully", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid date range" }, "errors": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "429": { "description": "Too Many Requests" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/donations/{id}/receipt": { "get": { "tags": [ "Donations" ], "summary": "Download donation receipt PDF", "description": "Download the PDF receipt for a specific donation. Returns 404 if receipt not found or not generated.", "operationId": "downloadReceipt", "parameters": [ { "name": "id", "in": "path", "description": "Donation ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Receipt PDF file", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Forbidden - User doesn't own this donation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You do not have permission to access this receipt" } }, "type": "object" } } } }, "404": { "description": "Receipt not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Receipt not found or not generated" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "429": { "description": "Too Many Requests" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/donations/tax-summary/download": { "get": { "tags": [ "Donations" ], "summary": "Download tax summary for financial year", "description": "Download a comprehensive tax summary (PDF or CSV) for all completed donations within a specified financial year or date range. Defaults to current Australian financial year (July 1 to June 30).", "operationId": "downloadTaxSummary", "parameters": [ { "name": "financial_year", "in": "query", "description": "Financial year starting year (e.g., 2024 for FY 2024-2025). If provided, overrides from_date and to_date.", "required": false, "schema": { "type": "integer", "example": 2024 } }, { "name": "from_date", "in": "query", "description": "Custom start date (Y-m-d format). Ignored if financial_year is provided.", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-07-01" } }, { "name": "to_date", "in": "query", "description": "Custom end date (Y-m-d format). Ignored if financial_year is provided.", "required": false, "schema": { "type": "string", "format": "date", "example": "2025-06-30" } }, { "name": "format", "in": "query", "description": "Export format (pdf or csv). Defaults to pdf.", "required": false, "schema": { "type": "string", "default": "pdf", "enum": [ "pdf", "csv" ] } } ], "responses": { "200": { "description": "Tax summary file (PDF or CSV)", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "No donations found for the specified period", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No donations found for the specified period" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "429": { "description": "Too Many Requests" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/homepage/sections": { "get": { "tags": [ "Homepage" ], "summary": "Get homepage sections", "description": "Retrieve all active homepage sections with their associated projects. This is a public endpoint with caching enabled.", "operationId": "getHomepageSections", "responses": { "200": { "description": "Homepage sections retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "oneOf": [ { "properties": { "section_key": { "type": "string", "example": "hero" }, "settings": { "type": "object", "nullable": true }, "project": { "description": "Single project for hero section", "type": "object", "nullable": true } }, "type": "object" }, { "properties": { "section_key": { "type": "string", "example": "weekly_project" }, "settings": { "type": "object", "nullable": true }, "projects": { "description": "Array of projects for weekly section", "type": "array", "items": { "type": "object" } } }, "type": "object" }, { "properties": { "section_key": { "type": "string", "example": "project_story" }, "settings": { "type": "object", "nullable": true }, "projects": { "description": "Array of exactly 4 projects for story section", "type": "array", "items": { "type": "object" } } }, "type": "object" } ] } } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred while fetching homepage sections." } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Too many requests. Please try again later." } }, "type": "object" } } } } } } }, "/api/user/recurring-donations": { "get": { "tags": [ "Recurring Donations" ], "summary": "Get user's recurring donations", "description": "Retrieve a paginated list of recurring donations (subscriptions) for the authenticated user", "operationId": "getRecurringDonations", "parameters": [ { "name": "status", "in": "query", "description": "Filter by status (active, paused, cancelled, expired, failed)", "required": false, "schema": { "type": "string", "enum": [ "active", "paused", "cancelled", "expired", "failed" ] } }, { "name": "sort_by", "in": "query", "description": "Field to sort by", "required": false, "schema": { "type": "string", "default": "next_billing_date", "enum": [ "next_billing_date", "created_at", "amount" ] } }, { "name": "sort_order", "in": "query", "description": "Sort order", "required": false, "schema": { "type": "string", "default": "asc", "enum": [ "asc", "desc" ] } }, { "name": "per_page", "in": "query", "description": "Number of items per page (default: 10, max: 100)", "required": false, "schema": { "type": "integer", "default": 10, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Recurring donations retrieved successfully", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "type": "object" } }, "meta": { "properties": { "total": { "type": "integer", "example": 12 }, "per_page": { "type": "integer", "example": 10 }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 2 }, "from": { "type": "integer", "example": 1 }, "to": { "type": "integer", "example": 10 } }, "type": "object" }, "links": { "properties": { "first": { "type": "string", "example": "http://example.com/api/user/recurring-donations?page=1" }, "last": { "type": "string", "example": "http://example.com/api/user/recurring-donations?page=2" }, "prev": { "type": "string", "example": null, "nullable": true }, "next": { "type": "string", "example": "http://example.com/api/user/recurring-donations?page=2", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Recurring Donations" ], "summary": "Create a new recurring donation", "description": "Create a new recurring donation (subscription) for the authenticated user", "operationId": "createRecurringDonation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "project_id", "currency_id", "amount", "frequency", "payment_method" ], "properties": { "project_id": { "description": "ID of the project to donate to", "type": "integer", "example": 1 }, "currency_id": { "description": "ID of the currency", "type": "integer", "example": 1 }, "amount": { "description": "Donation amount (minimum: 0.01)", "type": "number", "format": "float", "example": 50 }, "frequency": { "description": "Donation frequency", "type": "string", "enum": [ "daily", "weekly", "monthly", "quarterly", "yearly" ], "example": "monthly" }, "payment_method": { "description": "Payment method", "type": "string", "enum": [ "paypal", "stripe", "bank_transfer" ], "example": "paypal" } }, "type": "object" } } } }, "responses": { "201": { "description": "Recurring donation created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Recurring donation created successfully" }, "data": { "properties": { "id": { "type": "integer", "example": 1 }, "amount": { "type": "number", "example": 50 }, "frequency": { "type": "string", "example": "monthly" }, "status": { "type": "string", "example": "active" }, "next_billing_date": { "type": "string", "example": "7 Nov 2025" }, "total_amount_paid": { "type": "number", "example": 0 }, "total_payments": { "type": "integer", "example": 0 }, "project": { "type": "object" }, "currency": { "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to create recurring donation" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/user/recurring-donations/{id}": { "get": { "tags": [ "Recurring Donations" ], "summary": "Get a specific recurring donation", "description": "Retrieve details of a specific recurring donation (subscription) for the authenticated user", "operationId": "getRecurringDonation", "parameters": [ { "name": "id", "in": "path", "description": "Subscription ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Recurring donation details retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Recurring donation details retrieved successfully" }, "data": { "properties": { "id": { "type": "integer", "example": 1 }, "amount": { "type": "number", "example": 50 }, "frequency": { "type": "string", "example": "monthly" }, "status": { "type": "string", "example": "active" }, "next_billing_date": { "type": "string", "example": "7 Nov 2025" }, "project": { "type": "object" }, "currency": { "type": "object" }, "donations": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Subscription not found or you do not have permission to view it" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Recurring Donations" ], "summary": "Cancel a recurring donation", "description": "Cancel a recurring donation. Can cancel active or paused subscriptions. Optionally provide a cancellation reason.", "operationId": "cancelRecurringDonation", "parameters": [ { "name": "id", "in": "path", "description": "Subscription ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "cancellation_reason": { "description": "Optional reason for cancellation", "type": "string", "example": "No longer able to afford" } }, "type": "object" } } } }, "responses": { "200": { "description": "Recurring donation cancelled successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Recurring donation cancelled successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Subscription not found" }, "403": { "description": "Unauthorized" }, "422": { "description": "Invalid status transition" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/user/recurring-donations/{id}/pause": { "patch": { "tags": [ "Recurring Donations" ], "summary": "Pause a recurring donation", "description": "Pause an active recurring donation. Can only pause active subscriptions.", "operationId": "pauseRecurringDonation", "parameters": [ { "name": "id", "in": "path", "description": "Subscription ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Recurring donation paused successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Recurring donation paused successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Subscription not found" }, "403": { "description": "Unauthorized" }, "422": { "description": "Invalid status transition" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/user/recurring-donations/{id}/resume": { "patch": { "tags": [ "Recurring Donations" ], "summary": "Resume a paused recurring donation", "description": "Resume a paused recurring donation. Can only resume paused subscriptions.", "operationId": "resumeRecurringDonation", "parameters": [ { "name": "id", "in": "path", "description": "Subscription ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Recurring donation resumed successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Recurring donation resumed successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Subscription not found" }, "403": { "description": "Unauthorized" }, "422": { "description": "Invalid status transition" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/register": { "post": { "tags": [ "Authentication" ], "summary": "Register a new user", "description": "Create a new user account and receive an authentication token", "operationId": "registerUser", "requestBody": { "description": "User registration data", "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "password" ], "properties": { "name": { "description": "User's full name", "type": "string", "example": "John Doe" }, "email": { "description": "User's email address", "type": "string", "format": "email", "example": "john@example.com" }, "password": { "description": "Password (minimum 8 characters)", "type": "string", "format": "password", "minLength": 8, "example": "password123" }, "password_confirmation": { "description": "Password confirmation", "type": "string", "format": "password", "example": "password123" }, "phone": { "description": "User's phone number", "type": "string", "example": "+1234567890", "nullable": true }, "locale": { "description": "Preferred language", "type": "string", "default": "en", "enum": [ "en", "ar" ], "example": "en" } }, "type": "object" } } } }, "responses": { "201": { "description": "User registered successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "User registered successfully" }, "data": { "properties": { "user": { "type": "object" }, "token": { "description": "Sanctum authentication token", "type": "string", "example": "1|abcdef123456" }, "token_type": { "type": "string", "example": "Bearer" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Registration failed" }, "error": { "type": "string", "example": "An error occurred during registration. Please try again." } }, "type": "object" } } } } } } }, "/api/login": { "post": { "tags": [ "Authentication" ], "summary": "Login user", "description": "Authenticate user and receive an authentication token", "operationId": "loginUser", "requestBody": { "description": "User login credentials", "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "description": "User's email address", "type": "string", "format": "email", "example": "john@example.com" }, "password": { "description": "User's password", "type": "string", "format": "password", "example": "password123" } }, "type": "object" } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Login successful" }, "data": { "properties": { "user": { "type": "object" }, "token": { "description": "Sanctum authentication token", "type": "string", "example": "2|xyz789" }, "token_type": { "type": "string", "example": "Bearer" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Invalid credentials or inactive account", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Invalid credentials" }, "error": { "type": "string", "example": "The provided credentials are incorrect or account is inactive." } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Login failed" }, "error": { "type": "string", "example": "An error occurred during login. Please try again." } }, "type": "object" } } } } } } }, "/api/admin/login": { "post": { "tags": [ "Authentication" ], "summary": "Admin login", "description": "Authenticate admin and receive an authentication token. Only checks Admin model, not User model.", "operationId": "adminLogin", "requestBody": { "description": "Admin login credentials", "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "description": "Admin's email address", "type": "string", "format": "email", "example": "admin@example.com" }, "password": { "description": "Admin's password", "type": "string", "format": "password", "example": "password123" } }, "type": "object" } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Login successful" }, "data": { "properties": { "user": { "type": "object" }, "token": { "description": "Sanctum authentication token", "type": "string", "example": "2|xyz789" }, "token_type": { "type": "string", "example": "Bearer" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Invalid credentials or inactive account", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid credentials" }, "error": { "type": "string", "example": "The provided credentials are incorrect or account is inactive." } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Login failed" }, "error": { "type": "string", "example": "An error occurred during login. Please try again." } }, "type": "object" } } } } } } }, "/api/logout": { "post": { "tags": [ "Authentication" ], "summary": "Logout user", "description": "Revoke the current authentication token", "operationId": "logoutUser", "responses": { "200": { "description": "Logout successful", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Logout successful" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Logout failed" }, "error": { "type": "string", "example": "An error occurred during logout. Please try again." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/blogs": { "get": { "tags": [ "Blogs" ], "summary": "Get list of published blogs", "description": "Retrieve a paginated list of published blogs with filtering and sorting options. Only blogs with status 'published' are returned.", "operationId": "getBlogs", "parameters": [ { "name": "locale", "in": "query", "description": "Language locale (en, ar, or fr)", "required": false, "schema": { "type": "string", "default": "en", "enum": [ "en", "ar", "fr" ] } }, { "name": "sort_by", "in": "query", "description": "Field to sort by", "required": false, "schema": { "type": "string", "default": "created_at", "enum": [ "id", "created_at", "updated_at", "display_order", "title_en", "title_ar", "title_fr" ] } }, { "name": "sort_order", "in": "query", "description": "Sort order", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Search in title and description", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Blog" } }, "meta": { "properties": { "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object" } }, "type": "object" } } } } } } }, "/api/blogs/{slug}": { "get": { "tags": [ "Blogs" ], "summary": "Get blog details by slug", "description": "Retrieve detailed information about a specific published blog using its slug. For backward compatibility, numeric IDs are also supported but deprecated.", "operationId": "getBlogBySlug", "parameters": [ { "name": "slug", "in": "path", "description": "Blog slug (or legacy ID for backward compatibility)", "required": true, "schema": { "type": "string" } }, { "name": "locale", "in": "query", "description": "Language locale (en, ar, or fr)", "required": false, "schema": { "type": "string", "default": "en", "enum": [ "en", "ar", "fr" ] } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Blog" } } } }, "404": { "description": "Blog not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Blog not found" } }, "type": "object" } } } } } } }, "/api/blogs/recent": { "get": { "tags": [ "Blogs" ], "summary": "Get recent published blogs", "description": "Retrieve a list of recently published blogs, ordered by creation date", "operationId": "getRecentBlogs", "parameters": [ { "name": "locale", "in": "query", "description": "Language locale (en, ar, or fr)", "required": false, "schema": { "type": "string", "default": "en", "enum": [ "en", "ar", "fr" ] } }, { "name": "limit", "in": "query", "description": "Number of recent blogs to return", "required": false, "schema": { "type": "integer", "default": 6, "maximum": 20, "minimum": 1 } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Blog" } }, "meta": { "properties": { "count": { "type": "integer" }, "locale": { "type": "string" } }, "type": "object" } }, "type": "object" } } } } } } }, "/api/projects": { "get": { "tags": [ "Projects" ], "summary": "Get list of projects", "description": "Retrieve a paginated list of charity projects with filtering and sorting options", "operationId": "getProjects", "parameters": [ { "name": "locale", "in": "query", "description": "Language locale (en, ar, or fr)", "required": false, "schema": { "type": "string", "default": "en", "enum": [ "en", "ar", "fr" ] } }, { "name": "status", "in": "query", "description": "Filter by project status", "required": false, "schema": { "type": "string", "enum": [ "active", "completed", "pending", "cancelled" ] } }, { "name": "sort_by", "in": "query", "description": "Field to sort by", "required": false, "schema": { "type": "string", "default": "created_at", "enum": [ "created_at", "goal_amount", "current_amount", "start_date", "end_date", "donors_count" ] } }, { "name": "sort_order", "in": "query", "description": "Sort order", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "is_featured", "in": "query", "description": "Filter by featured projects", "required": false, "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "description": "Search in title and description", "required": false, "schema": { "type": "string" } }, { "name": "category_id", "in": "query", "description": "Filter by category ID", "required": false, "schema": { "type": "integer" } }, { "name": "category_slug", "in": "query", "description": "Filter by category slug (e.g., 'education', 'health')", "required": false, "schema": { "type": "string" } }, { "name": "region_id", "in": "query", "description": "Filter by region ID", "required": false, "schema": { "type": "integer" } }, { "name": "region_code", "in": "query", "description": "Filter by region code (e.g., 'PS', 'SY', 'YE')", "required": false, "schema": { "type": "string" } }, { "name": "region_ids", "in": "query", "description": "Filter by multiple region IDs (comma-separated or array)", "required": false, "schema": { "type": "array", "items": { "type": "integer" } } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "meta": { "properties": { "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object" } }, "type": "object" } } } } } } }, "/api/projects/slug/{slug}": { "get": { "tags": [ "Projects" ], "summary": "Get project details by slug", "description": "Retrieve detailed information about a specific charity project using its slug", "operationId": "getProjectBySlug", "parameters": [ { "name": "slug", "in": "path", "description": "Project slug", "required": true, "schema": { "type": "string" } }, { "name": "locale", "in": "query", "description": "Language locale (en, ar, or fr)", "required": false, "schema": { "type": "string", "default": "en", "enum": [ "en", "ar", "fr" ] } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Project not found" } }, "type": "object" } } } } } } }, "/api/projects/{id}": { "get": { "tags": [ "Projects" ], "summary": "Get project details", "description": "Retrieve detailed information about a specific charity project", "operationId": "getProjectById", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } }, { "name": "locale", "in": "query", "description": "Language locale (en, ar, or fr)", "required": false, "schema": { "type": "string", "default": "en", "enum": [ "en", "ar", "fr" ] } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Project not found" } }, "type": "object" } } } } } } }, "/api/projects/featured": { "get": { "tags": [ "Projects" ], "summary": "Get featured projects", "description": "Retrieve a list of featured charity projects", "operationId": "getFeaturedProjects", "parameters": [ { "name": "locale", "in": "query", "description": "Language locale (en, ar, or fr)", "required": false, "schema": { "type": "string", "default": "en", "enum": [ "en", "ar", "fr" ] } }, { "name": "limit", "in": "query", "description": "Number of featured projects to return", "required": false, "schema": { "type": "integer", "default": 6, "maximum": 20, "minimum": 1 } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "meta": { "type": "object" } }, "type": "object" } } } } } } }, "/api/projects/weekly": { "get": { "tags": [ "Projects" ], "summary": "Get weekly projects", "description": "Retrieve a list of projects marked as weekly projects from the admin dashboard", "operationId": "getWeeklyProjects", "parameters": [ { "name": "locale", "in": "query", "description": "Language locale (en, ar, or fr)", "required": false, "schema": { "type": "string", "default": "en", "enum": [ "en", "ar", "fr" ] } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "meta": { "properties": { "count": { "type": "integer" }, "locale": { "type": "string" } }, "type": "object" } }, "type": "object" } } } } } } }, "/api/admin/projects/stats": { "get": { "tags": [ "Admin - Projects" ], "summary": "Get project statistics", "description": "Retrieve aggregated project statistics including counts by status, urgent projects, and near completion projects. Uses database aggregations for optimal performance. Results are cached for 60 seconds. Admin access required.", "operationId": "getProjectStats", "parameters": [ { "name": "locale", "in": "query", "description": "Language locale (en, ar, or fr). Accepted for API consistency but not used in calculations as statistics are language-agnostic.", "required": false, "schema": { "type": "string", "default": "en", "enum": [ "en", "ar", "fr" ] } } ], "responses": { "200": { "description": "Statistics retrieved successfully", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "total": { "description": "Total number of projects", "type": "integer", "example": 150 }, "active": { "description": "Number of active projects", "type": "integer", "example": 45 }, "completed": { "description": "Number of completed projects", "type": "integer", "example": 80 }, "paused": { "description": "Number of paused projects", "type": "integer", "example": 10 }, "cancelled": { "description": "Number of cancelled projects", "type": "integer", "example": 5 }, "urgent": { "description": "Number of urgent projects (flagged or ending within 7 days)", "type": "integer", "example": 12 }, "near_completion": { "description": "Number of active projects with 80%+ completion", "type": "integer", "example": 8 } }, "type": "object" }, "meta": { "properties": { "cached": { "description": "Whether the result was served from cache", "type": "boolean", "example": true }, "cache_ttl": { "description": "Cache TTL in seconds", "type": "integer", "example": 60 }, "timestamp": { "description": "Response timestamp", "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "403": { "description": "Forbidden - Admin access required", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthorized." }, "error": { "type": "string", "example": "You do not have permission to access this resource." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "schemas": { "Project": { "title": "Project", "description": "Charity project model", "properties": { "id": { "type": "integer", "example": 1 }, "title": { "type": "string", "example": "Build a School in Rural Africa" }, "description": { "type": "string", "example": "Help us build a modern school facility..." }, "short_description": { "type": "string", "example": "Building a modern school for 500+ children" }, "category": { "description": "Category information", "properties": { "id": { "type": "integer", "example": 1 }, "slug": { "type": "string", "example": "education" }, "name": { "type": "string", "example": "Education" } }, "type": "object", "nullable": true }, "regions": { "description": "List of regions where the project is active", "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "PS" }, "name": { "type": "string", "example": "Palestine" } }, "type": "object" } }, "slug": { "type": "string", "example": "build-school-rural-africa" }, "goal_amount": { "type": "number", "format": "float", "example": 50000 }, "current_amount": { "type": "number", "format": "float", "example": 32500 }, "progress_percentage": { "type": "number", "format": "float", "example": 65 }, "remaining_amount": { "type": "number", "format": "float", "example": 17500 }, "currency": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "USD" }, "symbol": { "type": "string", "example": "$" } }, "type": "object" }, "start_date": { "type": "string", "format": "date", "example": "2024-01-01" }, "end_date": { "type": "string", "format": "date", "example": "2024-12-31" }, "is_active": { "type": "boolean", "example": true }, "days_remaining": { "type": "integer", "example": 120 }, "image": { "type": "string", "example": "path/to/image.jpg", "nullable": true }, "images": { "type": "array", "items": { "type": "string" }, "nullable": true }, "video_url": { "type": "string", "example": "https://youtube.com/watch?v=...", "nullable": true }, "status": { "type": "string", "enum": [ "active", "completed", "pending", "cancelled" ], "example": "active" }, "is_featured": { "type": "boolean", "example": true }, "allow_anonymous": { "type": "boolean", "example": true }, "donors_count": { "type": "integer", "example": 150 }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-01T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-10-27T14:30:00Z" } }, "type": "object" }, "Blog": { "title": "Blog", "description": "Blog post model", "properties": { "id": { "type": "integer", "example": 1 }, "slug": { "type": "string", "example": "charity-impact-2024" }, "title_en": { "type": "string", "example": "Charity Impact Report 2024" }, "title_ar": { "type": "string", "example": "تقرير تأثير الخير 2024", "nullable": true }, "title_fr": { "type": "string", "example": "Rapport d'impact caritatif 2024", "nullable": true }, "short_description_en": { "type": "string", "example": "A comprehensive overview of our charity work this year", "nullable": true }, "short_description_ar": { "type": "string", "example": "نظرة شاملة على عملنا الخيري هذا العام", "nullable": true }, "short_description_fr": { "type": "string", "example": "Un aperçu complet de notre travail caritatif cette année", "nullable": true }, "full_description_en": { "type": "string", "example": "Full detailed description of the blog post content...", "nullable": true }, "full_description_ar": { "type": "string", "example": "وصف مفصل كامل لمحتوى المقال...", "nullable": true }, "full_description_fr": { "type": "string", "example": "Description détaillée complète du contenu de l'article...", "nullable": true }, "image": { "type": "string", "example": "http://localhost:8000/storage/blogs/image.jpg", "nullable": true }, "image_url": { "type": "string", "example": "http://localhost:8000/storage/blogs/image.jpg", "nullable": true }, "display_order": { "type": "integer", "example": 1 }, "status": { "type": "string", "enum": [ "draft", "published", "archived" ], "example": "published" }, "creator": { "description": "Admin who created the blog", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "admin@example.com" } }, "type": "object", "nullable": true }, "created_by": { "type": "integer", "example": 1, "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-01T10:00:00Z", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-10-27T14:30:00Z", "nullable": true }, "deleted_at": { "type": "string", "format": "date-time", "example": null, "nullable": true } }, "type": "object" }, "User": { "title": "User", "description": "User model", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "user@example.com" }, "phone": { "type": "string", "example": "+1234567890", "nullable": true }, "locale": { "type": "string", "enum": [ "en", "ar", "fr" ], "example": "en" }, "role": { "type": "string", "example": "user", "nullable": true }, "is_active": { "type": "boolean", "example": true }, "avatar": { "type": "string", "example": "http://localhost:8000/storage/avatars/user.jpg", "nullable": true }, "provider": { "type": "string", "example": "google", "nullable": true }, "provider_id": { "type": "string", "example": "123456789", "nullable": true }, "business_name": { "type": "string", "example": "ABC Corporation", "nullable": true }, "abn": { "type": "string", "example": "12345678901", "nullable": true }, "country": { "type": "string", "example": "Australia", "nullable": true }, "gender": { "type": "string", "enum": [ "male", "female", "other" ], "example": "male", "nullable": true }, "birth_date": { "type": "string", "format": "date", "example": "1990-01-01", "nullable": true }, "region": { "description": "User's region", "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "PS" }, "name": { "type": "string", "example": "Palestine" }, "name_en": { "type": "string", "example": "Palestine", "nullable": true }, "name_ar": { "type": "string", "example": "فلسطين", "nullable": true }, "name_fr": { "type": "string", "example": "Palestine", "nullable": true }, "type": { "type": "string", "example": "country", "nullable": true } }, "type": "object", "nullable": true }, "default_currency": { "description": "User's default currency", "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "USD" }, "symbol": { "type": "string", "example": "$" }, "name": { "type": "string", "example": "US Dollar", "nullable": true }, "name_en": { "type": "string", "example": "US Dollar", "nullable": true }, "name_ar": { "type": "string", "example": "دولار أمريكي", "nullable": true }, "name_fr": { "type": "string", "example": "Dollar américain", "nullable": true }, "exchange_rate": { "type": "number", "format": "float", "example": 1, "nullable": true } }, "type": "object", "nullable": true }, "region_id": { "type": "integer", "example": 1, "nullable": true }, "default_currency_id": { "type": "integer", "example": 1, "nullable": true }, "email_verified_at": { "type": "string", "format": "date-time", "example": "2024-01-01T10:00:00Z", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-01T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-10-27T14:30:00Z" }, "deleted_at": { "type": "string", "format": "date-time", "example": null, "nullable": true } }, "type": "object" }, "Donation": { "title": "Donation", "description": "Donation model", "properties": { "id": { "type": "integer", "example": 1 }, "amount": { "type": "number", "format": "float", "example": 100.5 }, "amount_in_usd": { "type": "number", "format": "float", "example": 100.5, "nullable": true }, "status": { "type": "string", "enum": [ "pending", "completed", "failed", "cancelled" ], "example": "completed" }, "is_anonymous": { "type": "boolean", "example": false }, "is_gift": { "type": "boolean", "example": false }, "is_recurring": { "type": "boolean", "example": false }, "payment_method": { "type": "string", "example": "credit_card", "nullable": true }, "donation_type": { "type": "string", "enum": [ "regular", "anonymous", "gift", "zakat", "zakat_alfitr", "sadaqa", "fidya", "kafarah", "aqeeqah", "qurbani" ], "example": "regular", "nullable": true }, "donation_type_display": { "type": "string", "example": "Regular", "nullable": true }, "donor_name": { "type": "string", "example": "John Doe", "nullable": true }, "donor_email": { "type": "string", "format": "email", "example": "donor@example.com", "nullable": true }, "message": { "type": "string", "example": "Thank you for your support", "nullable": true }, "gift_recipient_name": { "type": "string", "example": "Jane Doe", "nullable": true }, "gift_recipient_email": { "type": "string", "format": "email", "example": "recipient@example.com", "nullable": true }, "gift_message": { "type": "string", "example": "Happy Birthday!", "nullable": true }, "currency": { "description": "Donation currency", "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "USD" }, "symbol": { "type": "string", "example": "$" }, "name": { "type": "string", "example": "US Dollar", "nullable": true } }, "type": "object", "nullable": true }, "projects": { "description": "Projects associated with this donation", "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "title": { "type": "string", "example": "Build a School" }, "slug": { "type": "string", "example": "build-school" }, "pivot_amount": { "type": "number", "format": "float", "example": 100.5 }, "pivot_amount_in_usd": { "type": "number", "format": "float", "example": 100.5 }, "frequency": { "type": "string", "example": "monthly", "nullable": true } }, "type": "object" }, "nullable": true }, "primary_project": { "description": "Primary project for this donation", "properties": { "id": { "type": "integer", "example": 1 }, "title": { "type": "string", "example": "Build a School" }, "slug": { "type": "string", "example": "build-school" }, "pivot_amount": { "type": "number", "format": "float", "example": 100.5 }, "pivot_amount_in_usd": { "type": "number", "format": "float", "example": 100.5 } }, "type": "object", "nullable": true }, "subscription": { "description": "Recurring subscription information", "properties": { "id": { "type": "integer", "example": 1 }, "frequency": { "type": "string", "example": "monthly" }, "status": { "type": "string", "example": "active" }, "next_billing_date": { "type": "string", "format": "date", "example": "2024-02-01", "nullable": true }, "total_payments": { "type": "integer", "example": 5 }, "total_amount_paid": { "type": "number", "format": "float", "example": 500 } }, "type": "object", "nullable": true }, "user_id": { "type": "integer", "example": 1, "nullable": true }, "currency_id": { "type": "integer", "example": 1, "nullable": true }, "subscription_id": { "type": "integer", "example": 1, "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "example": "2024-01-01T10:00:00Z", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-01T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-10-27T14:30:00Z" }, "deleted_at": { "type": "string", "format": "date-time", "example": null, "nullable": true } }, "type": "object" } }, "securitySchemes": { "bearerAuth": { "type": "http", "description": "Enter your Sanctum token. Get it from /api/login endpoint", "bearerFormat": "JWT", "scheme": "bearer" } } }, "tags": [ { "name": "Admin - Blogs", "description": "Admin endpoints for managing blog posts" }, { "name": "Admin - Categories", "description": "Admin endpoints for managing categories" }, { "name": "Admin - Admins", "description": "Admin endpoints for managing administrators" }, { "name": "Admin - Dashboard", "description": "Admin dashboard endpoints for statistics and activities" }, { "name": "Admin - Homepage Sections", "description": "Admin endpoints for managing homepage sections" }, { "name": "Admin - Projects", "description": "Admin endpoints for managing charity projects" }, { "name": "Admin - Regions", "description": "Admin endpoints for managing regions" }, { "name": "Admin - Reports", "description": "Admin endpoints for reports and statistics" }, { "name": "Cart", "description": "API endpoints for managing donation cart" }, { "name": "Checkout", "description": "API endpoints for donation checkout flow" }, { "name": "Donations", "description": "API endpoints for managing donations" }, { "name": "Homepage", "description": "Public endpoints for homepage sections" }, { "name": "Recurring Donations", "description": "API endpoints for managing recurring donations (subscriptions)" }, { "name": "Admin - Donations", "description": "Admin - Donations" }, { "name": "Authentication", "description": "Authentication" }, { "name": "Blogs", "description": "Blogs" }, { "name": "Projects", "description": "Projects" } ] }