openapi: 3.0.3 info: title: TEFAS Fund API description: | Comprehensive REST API for Turkish Electronic Fund Trading Platform (TEFAS) data. This API provides real-time and historical data for Turkish mutual funds, including: - Fund performance metrics and returns analysis - Portfolio management company information - Trading volume reports and institutional statistics - BEFAS (Individual Pension Funds Brokerage System) data - Advanced caching and admin management tools **Data Sources:** - TEFAS Official Website (www.tefas.gov.tr) - BEFAS Reporting System - Real-time web scraping with ChromeDP **Performance Features:** - Redis-based caching for optimal response times - Rate limiting and load balancing - Comprehensive error handling and monitoring **Last Updated:** December 2025 version: 2.1.0 contact: name: API Support Team email: serifcolakel0@gmail.com url: https://github.com/serifcolakel/go-tefas-scraper license: name: MIT url: https://opensource.org/licenses/MIT servers: - url: http://localhost:8080/ description: Development server - url: http://ec2-51-21-48-250.eu-north-1.compute.amazonaws.com:8080/ description: Production Server tags: - name: System description: System health and API information endpoints - name: Funds description: Core fund operations and data retrieval - name: Fund Returns description: Fund performance and return data - name: Trading Reports description: Trading statistics and institutional reports - name: BEFAS description: BEFAS (Bireysel Emeklilik Fonları Aracılık Sistemi) fund statistics and reports - name: Cron Jobs description: Cron job management and monitoring - name: Images description: Image upload, management and serving - name: Utilities description: Cache management and administrative operations paths: /info: get: tags: - System summary: API Root description: Returns basic API information responses: '200': description: Successful response content: application/json: schema: type: object properties: message: type: string version: type: string status: type: string time: type: string format: date-time /api/v1/healthz: get: tags: - System summary: Health Check description: Returns the health status of the API and its dependencies responses: '200': description: Service is healthy content: application/json: schema: type: object properties: status: type: string enum: - healthy time: type: string format: date-time '503': description: Service is unhealthy content: application/json: schema: type: object properties: status: type: string enum: - unhealthy error: type: string /api/v1/funds: get: tags: - Funds summary: Get All Funds description: Retrieves a list of all available funds responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/FundListResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/funds/companies: get: tags: - Funds summary: Get All Portfolio Management Companies description: | Retrieves a comprehensive list of all portfolio management companies operating in Turkey's fund market. **Data Source:** - Dynamically scraped from TEFAS website dropdown menus - Updates automatically when fund comparison endpoints are called - Includes companies across all fund types (YAT, EMK, BYF, GYF, GSYF) **Company Categories:** - **YAT**: Yatırım Fonları (Investment Funds) management companies - **EMK**: Emeklilik Fonları (Pension Funds) management companies - **BYF**: Borsa Yatırım Fonları (ETF) management companies - **GYF**: Gayrimenkul Yatırım Fonları (Real Estate Funds) management companies - **GSYF**: Girişim Sermayesi Yatırım Fonları (Venture Capital Funds) management companies **Response Format:** Each company includes: - **code**: 3-character unique company identifier (e.g., AKP, ZPY, ISP) - **company**: Full legal company name - **category**: Fund type category the company operates in **Use Cases:** - Populate dropdown lists for company filtering - Validate company codes in fund queries - Display company information in UI - Filter funds by portfolio management company **Note:** Company list is automatically updated when calling fund comparison endpoints (/api/v1/funds/returns, /api/v1/funds/sizes, /api/v1/funds/comparison) responses: '200': description: Successful response with list of portfolio management companies content: application/json: schema: $ref: '#/components/schemas/CompanyResponse' examples: success: value: success: true data: - code: "AKP" company: "AK PORTFÖY YÖNETİMİ A.Ş." category: "YAT" - code: "ZPY" company: "ZİRAAT PORTFÖY YÖNETİMİ A.Ş." category: "YAT" - code: "ISP" company: "İŞ PORTFÖY YÖNETİMİ A.Ş." category: "YAT" - code: "FNV" company: "FONMAP PORTFÖY YÖNETİMİ ANONİM ŞİRKETİ" category: "YAT" meta: total: 150 '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/funds/{code}: get: tags: - Funds summary: Get Fund Details description: Retrieves detailed information for a specific fund with optional period filtering parameters: - name: code in: path required: true description: Fund code (3-6 alphanumeric characters) schema: type: string minLength: 3 maxLength: 6 pattern: ^[A-Za-z0-9]+$ example: YLB responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/FundResponse' '400': description: Invalid fund code content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/funds/{code}/{period}: get: tags: - Funds summary: Get Fund Details with Period description: Retrieves detailed information for a specific fund with optional period filtering parameters: - name: code in: path required: true description: Fund code (3-6 alphanumeric characters) schema: type: string minLength: 3 maxLength: 6 pattern: ^[A-Za-z0-9]+$ example: YLB - name: period in: path required: true description: Period filter (e.g., 1W (1 Week), 1M (1 Month), 3M (3 Months), 6M (6 Months), YTD (Year to Date), 1Y (1 Year), 3Y (3 Years), 5Y (5 Years)) schema: type: string enum: - 1W - 1M - 3M - 6M - YTD - 1Y - 3Y - 5Y - ALL pattern: ^(1W|1M|3M|6M|YTD|1Y|3Y|5Y|ALL)$ default: 1Y responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/FundResponse' '400': description: Invalid fund code content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/fund-info/history/{code}: get: tags: - Funds summary: Get Fund Historical Data from Database description: | Retrieves fund historical price data from PostgreSQL database with optional pagination. **Data Source:** PostgreSQL database (fund_line_values table) **Cache Strategy:** Redis cache with 1-hour TTL **Features:** - Returns all historical data if no pagination parameters provided - Supports limit/offset pagination - Supports page-based pagination - Data ordered by date descending (newest first) - Includes comprehensive metadata (total count, pagination info) **Use Cases:** - Display fund price history charts - Analyze fund performance over time - Export historical data - Build custom analytics **Performance:** - First request: Database query (cached for 1 hour) - Subsequent requests: Served from Redis cache - Efficient pagination with LIMIT/OFFSET **Response includes:** - Fund code - Date (YYYY-MM-DD format) - Value (fund price) - Created/Updated timestamps parameters: - name: code in: path required: true description: Fund code (3-6 alphanumeric characters, validated against fund list) schema: type: string minLength: 3 maxLength: 6 pattern: ^[A-Za-z0-9]+$ example: YLB - name: limit in: query description: Maximum number of records to return (1-1000). If not provided, returns all records. schema: type: integer minimum: 1 maximum: 1000 example: 50 - name: offset in: query description: Number of records to skip for pagination (used with limit) schema: type: integer minimum: 0 default: 0 example: 0 - name: page in: query description: Page number for page-based pagination (starts from 1). If provided with limit, offset is calculated automatically. schema: type: integer minimum: 1 example: 1 responses: '200': description: Fund historical data retrieved successfully content: application/json: schema: $ref: '#/components/schemas/FundHistoryResponse' examples: all_data: summary: All historical data (no pagination) value: data: - fundCode: YLB date: "2026-01-24" value: 1.234567 createdAt: "2026-01-24T10:00:00Z" updatedAt: "2026-01-24T10:00:00Z" - fundCode: YLB date: "2026-01-23" value: 1.234000 createdAt: "2026-01-23T10:00:00Z" updatedAt: "2026-01-23T10:00:00Z" success: true meta: total: 500 process_time: 50000000 message: "Fund history retrieved successfully for YLB" paginated: summary: Paginated data with limit and offset value: data: - fundCode: YLB date: "2026-01-24" value: 1.234567 createdAt: "2026-01-24T10:00:00Z" updatedAt: "2026-01-24T10:00:00Z" success: true meta: total: 500 page: 1 size: 50 total_pages: 10 has_more: true next_page: 2 process_time: 30000000 message: "Fund history retrieved successfully for YLB" '400': description: Invalid parameters or fund code content: application/json: schema: $ref: '#/components/schemas/APIError' examples: invalid_fund_code: summary: Invalid fund code value: error: "Invalid fund code" details: "fund not found: INVALID" status: 400 correlationId: "abc-123" suggestion: "Please check your request parameters and try again" occurredAt: "2026-01-24T12:00:00Z" invalid_limit: summary: Invalid limit parameter value: error: "Invalid parameters" details: "limit must be between 1 and 1000" status: 400 correlationId: "abc-123" suggestion: "Please check your request parameters and try again" occurredAt: "2026-01-24T12:00:00Z" '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/fund-info/by-date: get: tags: - Funds summary: Get Latest Fund Data by Date description: | Retrieves the latest fund data for a specific date with automatic weekend handling. **Data Source:** PostgreSQL database (fund_line_values table) **Cache Strategy:** - Today's data: 30 minutes TTL - Historical data: 24 hours TTL **Weekend Handling (Automatic):** - Saturday → Returns Friday's data - Sunday → Returns Friday's data - Weekday → Returns same day's data - Implemented at SQL level for consistency **Flexible Filtering:** - No filter: Returns all funds for the date - Single fund: `?fundCode=YLB` - Multiple funds: `?fundCodes=YLB,AAK,ZPY` **Sorting & Pagination:** - Sort by: value, date, or fund_code - Sort order: asc or desc - Pagination: limit/offset or page-based **Use Cases:** - Display daily fund prices - Compare multiple funds on same date - Build fund comparison charts - Daily performance reports **Performance:** - SQL-level weekend detection (no application logic needed) - Parameterized queries (SQL injection safe) - Redis caching for optimal response times - Efficient pagination with PostgreSQL parameters: - name: date in: query description: Date in YYYY-MM-DD format. If not provided, uses current date with weekend handling. schema: type: string format: date pattern: ^\d{4}-\d{2}-\d{2}$ example: "2026-01-20" - name: fundCode in: query description: Single fund code (3-6 characters). Cannot be used with fundCodes parameter. schema: type: string minLength: 3 maxLength: 6 pattern: ^[A-Za-z0-9]+$ example: YLB - name: fundCodes in: query description: Comma-separated fund codes (e.g., "YLB,AAK,ZPY"). Cannot be used with fundCode parameter. schema: type: string pattern: ^[A-Za-z0-9]+(,[A-Za-z0-9]+)*$ example: "YLB,AAK,ZPY" - name: limit in: query description: Maximum number of records to return (1-1000) schema: type: integer minimum: 1 maximum: 1000 default: 50 example: 50 - name: offset in: query description: Number of records to skip for pagination schema: type: integer minimum: 0 default: 0 example: 0 - name: page in: query description: Page number for page-based pagination (starts from 1) schema: type: integer minimum: 1 example: 1 - name: sortBy in: query description: Field to sort by schema: type: string enum: [value, date, fund_code] default: fund_code example: value - name: sortOrder in: query description: Sort order schema: type: string enum: [asc, desc, ASC, DESC] default: asc example: desc responses: '200': description: Latest fund data retrieved successfully content: application/json: schema: $ref: '#/components/schemas/LatestFundDataByDateResponse' examples: all_funds: summary: All funds for specific date value: data: - fundCode: YLB date: "2026-01-20" value: 1.234567 createdAt: "2026-01-20T10:00:00Z" updatedAt: "2026-01-20T10:00:00Z" - fundCode: AAK date: "2026-01-20" value: 2.345678 createdAt: "2026-01-20T10:00:00Z" updatedAt: "2026-01-20T10:00:00Z" success: true meta: total: 150 page: 1 size: 50 total_pages: 3 has_more: true next_page: 2 process_time: 45000000 message: "Latest fund data retrieved successfully for date 2026-01-20 (all funds)" single_fund: summary: Single fund for specific date value: data: - fundCode: YLB date: "2026-01-20" value: 1.234567 createdAt: "2026-01-20T10:00:00Z" updatedAt: "2026-01-20T10:00:00Z" success: true meta: total: 1 process_time: 25000000 message: "Latest fund data retrieved successfully for date 2026-01-20 (fund: YLB)" multiple_funds: summary: Multiple specific funds value: data: - fundCode: YLB date: "2026-01-20" value: 1.234567 createdAt: "2026-01-20T10:00:00Z" updatedAt: "2026-01-20T10:00:00Z" - fundCode: AAK date: "2026-01-20" value: 2.345678 createdAt: "2026-01-20T10:00:00Z" updatedAt: "2026-01-20T10:00:00Z" success: true meta: total: 2 process_time: 30000000 message: "Latest fund data retrieved successfully for date 2026-01-20 (multiple funds)" weekend_handling: summary: Weekend date automatically handled value: data: - fundCode: YLB date: "2026-01-23" value: 1.234567 createdAt: "2026-01-23T10:00:00Z" updatedAt: "2026-01-23T10:00:00Z" success: true meta: total: 150 process_time: 40000000 message: "Latest fund data retrieved successfully for date 2026-01-23 (all funds) - Weekend date automatically adjusted to last business day" '400': description: Invalid parameters content: application/json: schema: $ref: '#/components/schemas/APIError' examples: invalid_date: summary: Invalid date format value: error: "Invalid parameters" details: "date format must be YYYY-MM-DD" status: 400 correlationId: "abc-123" suggestion: "Please check your request parameters and try again" occurredAt: "2026-01-24T12:00:00Z" mutual_exclusive: summary: Both fundCode and fundCodes provided value: error: "Invalid parameters" details: "fundCode and fundCodes are mutually exclusive - use only one" status: 400 correlationId: "abc-123" suggestion: "Please check your request parameters and try again" occurredAt: "2026-01-24T12:00:00Z" invalid_fund_code: summary: Invalid fund code value: error: "Invalid fund code" details: "fund not found: INVALID" status: 400 correlationId: "abc-123" suggestion: "Please check your request parameters and try again" occurredAt: "2026-01-24T12:00:00Z" '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/funds/returns: get: tags: - Fund Returns summary: Get Fund Returns description: Retrieves fund return data by fund type with optional date filtering parameters: - name: fundType in: query description: Fund type (1=Menkul Kıymet, 2=Emeklilik, 3=Borsa, 4=Gayrimenkul, 5=Girişim Sermayesi) schema: type: string enum: - '1' - '2' - '3' - '4' - '5' default: '1' - name: startDate in: query description: Start date in dd.mm.yyyy format (optional) schema: type: string pattern: ^[0-9]{2}\.[0-9]{2}\.[0-9]{4}$ example: 01.01.2024 - name: endDate in: query description: End date in dd.mm.yyyy format (optional) schema: type: string pattern: ^[0-9]{2}\.[0-9]{2}\.[0-9]{4}$ example: 31.12.2024 - name: kurucuKod in: query description: | Portfolio management company code (founder code). - Use '*' or leave empty for all companies (default) - Use a valid 3-character company code (e.g., AKP, MUP, ZPY) for specific company **Available Company Codes:** AKP, MUP, PGA, ABO, ZRA, APY, ALA, TLR, GPO, BLP, BVP, EPY, FIP, GRP, FNV, FTP, EUP, HFP, GEP, IGR, IGP, ISY, ISP, KGY, KPO, KTP, LCP, LPO, MAP, MGY, NTR, VVP, NRL, OGP, ORG, OPO, PA1, PRT, IEP, FPY, PIE, ROP, TCR, SKP, KIG, UNP, VPG, KCP, ZPY, YGP schema: type: string default: '*' pattern: ^(\*|[A-Z]{3})$ example: 'AKP' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/FundReturnsResponse' '400': description: Invalid parameters content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/funds/returns/{page}: get: tags: - Fund Returns summary: Get Fund Returns with Pagination description: Retrieves fund return data with pagination parameters: - name: page in: path required: true description: Page number (starts from 1) schema: type: integer minimum: 1 - name: size in: query description: Number of items per page schema: type: integer minimum: 1 maximum: 250 default: 50 - name: fundType in: query description: Fund type (1=Menkul Kıymet, 2=Emeklilik, 3=Borsa, 4=Gayrimenkul, 5=Girişim Sermayesi) schema: type: string enum: - '1' - '2' - '3' - '4' - '5' default: '1' - name: startDate in: query description: Start date in dd.mm.yyyy format (optional) schema: type: string pattern: ^[0-9]{2}\.[0-9]{2}\.[0-9]{4}$ example: 01.01.2024 - name: endDate in: query description: End date in dd.mm.yyyy format (optional) schema: type: string pattern: ^[0-9]{2}\.[0-9]{2}\.[0-9]{4}$ example: 31.12.2024 - name: kurucuKod in: query description: | Portfolio management company code (founder code). - Use '*' or leave empty for all companies (default) - Use a valid 3-character company code (e.g., AKP, MUP, ZPY) for specific company schema: type: string default: '*' pattern: ^(\*|[A-Z]{3})$ example: 'AKP' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/PaginatedFundReturnsResponse' '400': description: Invalid parameters content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/funds/returns-by-date: get: tags: - Fund Returns summary: Get Fund Returns by Date description: | Retrieves comprehensive fund return data for all fund types for a specific date, grouped by fund type with enhanced weekend handling capabilities. **Enhanced Weekend Date Handling (New Feature):** - **Default Behavior**: Weekend requests (Saturday/Sunday) return HTTP 500 error with detailed guidance - **Flexible Mode**: Set `lastBusinessDay=true` to automatically get last trading day data for weekends - **Smart Validation**: Automatic business day detection with suggestions **Business Rules:** - Turkish stock market operates Monday-Friday only (excluding holidays) - Weekend dates without `lastBusinessDay=true` parameter will return informative errors - Future dates are not allowed (validation based on current date: December 2025) - Historical data available from 2015 onwards **Data Source**: TEFAS (Turkish Electronic Fund Trading Platform) BindHistoryInfo API **Cache TTL**: 1 hour for performance optimization **Fund Types Included**: - YAT (Yatırım Fonları) - Investment Funds - EMK (Emeklilik Fonları) - Pension Funds - BYF (Borsa Yatırım Fonları) - Exchange Traded Funds - GYF (Gayrimenkul Yatırım Fonları) - Real Estate Investment Funds - GSYF (Girişim Sermayesi Yatırım Fonları) - Venture Capital Investment Funds Each fund type includes totals and individual fund details with price, share count, investor count, and portfolio size. parameters: - name: date in: query required: true description: | Date in dd.mm.yyyy format (Turkish format). **Examples:** - Business day: `07.11.2025` (Friday) - Works normally - Weekend: `08.11.2025` (Saturday) - Requires `lastBusinessDay=true` or returns error - Weekend: `09.11.2025` (Sunday) - Requires `lastBusinessDay=true` or returns error schema: type: string pattern: ^[0-9]{2}\.[0-9]{2}\.[0-9]{4}$ example: 07.11.2025 - name: lastBusinessDay in: query required: false description: | **Weekend Date Handling Control Parameter** Determines how the API responds to weekend date requests: **Values:** - `true`: **Flexible Mode** - Weekend dates automatically return last business day data - Saturday → Friday data - Sunday → Friday data - Includes informative message about date substitution - `false` or omitted: **Strict Mode** - Weekend dates return HTTP 500 error - Error includes helpful guidance for users - Suggests adding `lastBusinessDay=true` parameter - Provides last available trading day information **Default**: `false` (strict validation for backward compatibility) **Use Cases:** - **Strict Financial Apps**: Omit parameter to ensure no accidental weekend requests - **User-Friendly UIs**: Set `true` for seamless weekend handling - **Automated Systems**: Set `true` for reliable data access regardless of request day **Error Message Example (when `false` or omitted):** ``` "Requested date (08.11.2025) is a Saturday. Turkish stock market operates Monday-Friday only. Last available trading day is 07.11.2025 (Friday). To automatically get last business day data, add parameter: lastBusinessDay=true" ``` schema: type: boolean default: false example: true # Usage Examples externalDocs: url: https://www.tefas.gov.tr description: | **API Usage Examples** **1. Business Day Request (Recommended)** ```bash GET /api/v1/funds/returns-by-date?date=07.11.2025 # ✅ Returns data for Friday (normal business day) ``` **2. Weekend Request - Strict Mode (Default)** ```bash GET /api/v1/funds/returns-by-date?date=08.11.2025 # ❌ Returns HTTP 500 error with helpful guidance # Error suggests adding lastBusinessDay=true ``` **3. Weekend Request - Flexible Mode** ```bash GET /api/v1/funds/returns-by-date?date=08.11.2025&lastBusinessDay=true # ✅ Returns Friday 07.11.2025 data with substitution message ``` **4. Programming Examples** **JavaScript/TypeScript:** ```javascript // Flexible weekend handling const response = await fetch('/api/v1/funds/returns-by-date?date=08.11.2025&lastBusinessDay=true'); const data = await response.json(); // Strict validation const strictResponse = await fetch('/api/v1/funds/returns-by-date?date=08.11.2025'); // Will throw error for weekend dates ``` **Python:** ```python import requests # Flexible mode response = requests.get('/api/v1/funds/returns-by-date', params={ 'date': '08.11.2025', 'lastBusinessDay': True }) # Strict mode response = requests.get('/api/v1/funds/returns-by-date', params={ 'date': '08.11.2025' }) # Will return 500 error for weekend ``` **cURL:** ```bash # Flexible weekend handling curl "http://localhost:8080/api/v1/funds/returns-by-date?date=08.11.2025&lastBusinessDay=true" # Strict weekend validation curl "http://localhost:8080/api/v1/funds/returns-by-date?date=08.11.2025" ``` responses: '200': description: | **Successful Response** Returns fund returns data grouped by fund type. Response includes: - Fund data grouped by type (YAT, EMK, BYF, GYF, GSYF) - Total fund count per fund type - Overall metadata with total fund count - Success message (may include weekend date substitution info) **Weekend Handling Success**: When `lastBusinessDay=true` is used for weekend dates, the response will include a message indicating the date substitution. content: application/json: schema: $ref: '#/components/schemas/FundReturnsByDateResponse' examples: business_day_success: summary: Business Day Request (Normal) description: Standard successful response for business day (e.g., Friday) value: data: - fund_type: "YAT" fund_type_name: "Yatırım Fonları" total: 42 funds: - date: "07.11.2025" fund_code: "AKL" fund_name: "Akbank Para Piyasası Fonu" price: 1.234567 share_count: 15000000 investor_count: 1250 portfolio_size: 150000000.5 - fund_type: "EMK" fund_type_name: "Emeklilik Fonları" total: 28 funds: [] meta: total: 156 success: true message: "Fund returns by date retrieved successfully" weekend_with_lastBusinessDay: summary: Weekend Request with lastBusinessDay=true description: Successful response when weekend date is requested with lastBusinessDay=true parameter value: data: - fund_type: "YAT" fund_type_name: "Yatırım Fonları" total: 42 funds: - date: "07.11.2025" fund_code: "AKL" fund_name: "Akbank Para Piyasası Fonu" price: 1.234567 share_count: 15000000 investor_count: 1250 portfolio_size: 150000000.5 meta: total: 156 success: true message: "Weekend date (08.11.2025) detected. Returning data for last business day: 07.11.2025 (Friday)" '400': description: | **Bad Request** Invalid request parameters such as: - Invalid date format (must be dd.mm.yyyy) - Future dates (beyond current date) - Malformed query parameters content: application/json: schema: $ref: '#/components/schemas/APIError' examples: invalid_date_format: summary: Invalid Date Format value: success: false error: "validation error" details: "invalid date format, expected dd.mm.yyyy" status: 400 correlationId: "req-12345" suggestion: "Use date format: dd.mm.yyyy (e.g., 15.10.2025)" severity: "medium" occurredAt: "2025-11-15T10:30:00Z" '404': description: Page not found content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: | **Internal Server Error** This includes weekend date validation errors when `lastBusinessDay` parameter is `false` or not provided. The error response provides helpful guidance for weekend date requests. content: application/json: schema: $ref: '#/components/schemas/APIError' examples: weekend_date_error: summary: Weekend Date Error (Strict Mode) description: Error response when weekend date is requested without lastBusinessDay=true value: success: false error: "weekend date not allowed" details: "Requested date (08.11.2025) is a Saturday. Turkish stock market operates Monday-Friday only. Last available trading day is 07.11.2025 (Friday). To automatically get last business day data, add parameter: lastBusinessDay=true" status: 500 correlationId: "req-12345" suggestion: "Add lastBusinessDay=true parameter to get last business day data for weekends" severity: "high" occurredAt: "2025-11-15T10:30:00Z" scraping_error: summary: Data Scraping Error value: success: false error: "scraping error" details: "Failed to retrieve fund data from TEFAS platform" status: 500 correlationId: "req-12346" suggestion: "Please try again later or contact support if the issue persists" severity: "high" occurredAt: "2025-11-15T10:30:00Z" /api/v1/funds/sizes: get: tags: - Fund Returns summary: Get Fund Sizes description: Retrieves fund size data by fund type with optional date filtering parameters: - name: fundType in: query description: Fund type (1=Menkul Kıymet, 2=Emeklilik, 3=Borsa, 4=Gayrimenkul, 5=Girişim Sermayesi) schema: type: string enum: - '1' - '2' - '3' - '4' - '5' default: '1' - name: startDate in: query description: Start date in dd.mm.yyyy format (optional) schema: type: string pattern: ^[0-9]{2}\.[0-9]{2}\.[0-9]{4}$ example: 01.01.2024 - name: endDate in: query description: End date in dd.mm.yyyy format (optional) schema: type: string pattern: ^[0-9]{2}\.[0-9]{2}\.[0-9]{4}$ example: 31.12.2024 - name: kurucuKod in: query description: | Portfolio management company code (founder code). - Use '*' or leave empty for all companies (default) - Use a valid 3-character company code (e.g., AKP, MUP, ZPY) for specific company **Available Company Codes:** AKP, MUP, PGA, ABO, ZRA, APY, ALA, TLR, GPO, BLP, BVP, EPY, FIP, GRP, FNV, FTP, EUP, HFP, GEP, IGR, IGP, ISY, ISP, KGY, KPO, KTP, LCP, LPO, MAP, MGY, NTR, VVP, NRL, OGP, ORG, OPO, PA1, PRT, IEP, FPY, PIE, ROP, TCR, SKP, KIG, UNP, VPG, KCP, ZPY, YGP schema: type: string default: '*' pattern: ^(\*|[A-Z]{3})$ example: 'AKP' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/FundSizesResponse' '400': description: Invalid parameters content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/funds/sizes/{page}: get: tags: - Fund Returns summary: Get Fund Sizes with Pagination description: Retrieves fund size data with pagination parameters: - name: page in: path required: true description: Page number (starts from 1) schema: type: integer minimum: 1 - name: size in: query description: Number of items per page schema: type: integer minimum: 1 maximum: 250 default: 50 - name: fundType in: query description: Fund type (1=Menkul Kıymet, 2=Emeklilik, 3=Borsa, 4=Gayrimenkul, 5=Girişim Sermayesi) schema: type: string enum: - '1' - '2' - '3' - '4' - '5' default: '1' - name: startDate in: query description: Start date in dd.mm.yyyy format (optional) schema: type: string pattern: ^[0-9]{2}\.[0-9]{2}\.[0-9]{4}$ example: 01.01.2024 - name: endDate in: query description: End date in dd.mm.yyyy format (optional) schema: type: string pattern: ^[0-9]{2}\.[0-9]{2}\.[0-9]{4}$ example: 31.12.2024 - name: kurucuKod in: query description: | Portfolio management company code (founder code). - Use '*' or leave empty for all companies (default) - Use a valid 3-character company code (e.g., AKP, MUP, ZPY) for specific company schema: type: string default: '*' pattern: ^(\*|[A-Z]{3})$ example: 'AKP' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/PaginatedFundSizesResponse' '400': description: Invalid parameters content: application/json: schema: $ref: '#/components/schemas/APIError' '404': description: Page not found content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/funds/historical: get: tags: - Fund Returns summary: Get Fund Historical Data description: | Retrieves comprehensive historical fund data by fund type with flexible date filtering and enhanced performance metrics. **Fund Types (Numeric Mapping):** - 1 = Menkul Kıymet Yatırım Fonları (Securities Investment Funds) - 2 = Emeklilik Yatırım Fonları (Pension Investment Funds) - 3 = Borsa Yatırım Fonları (Exchange Traded Funds) - 4 = Gayrimenkul Yatırım Fonları (Real Estate Investment Funds) - 5 = Girişim Sermayesi Yatırım Fonları (Venture Capital Investment Funds) **Enhanced Features:** - Borsa bulletin price data included - Participant count and share distribution metrics - Portfolio size calculations and analysis - Date range validation (2015 - December 2025) **Data Source:** TEFAS BindHistoryInfo API endpoint **Cache TTL:** 30 minutes for performance optimization **Default Date Range:** Last 7 days if not specified **Response Format:** Structured data with fund details, pricing, and portfolio metrics parameters: - name: fundType in: query description: Fund type (1=Menkul Kıymet, 2=Emeklilik, 3=Borsa, 4=Gayrimenkul, 5=Girişim Sermayesi) schema: type: string enum: - '1' - '2' - '3' - '4' - '5' default: '1' - name: startDate in: query description: Start date in dd.mm.yyyy format (defaults to 7 days ago) schema: type: string pattern: ^[0-9]{2}\.[0-9]{2}\.[0-9]{4}$ example: 01.08.2025 - name: endDate in: query description: End date in dd.mm.yyyy format (defaults to today) schema: type: string pattern: ^[0-9]{2}\.[0-9]{2}\.[0-9]{4}$ example: 16.08.2025 responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/FundHistoricalResponse' '400': description: Invalid parameters content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/funds/historical/{page}: get: tags: - Fund Returns summary: Get Fund Historical Data with Pagination description: | Retrieves fund historical data with pagination support for better performance with large datasets. **Fund Types:** - 1 = Menkul Kıymet Yatırım Fonları (Securities Investment Funds) - 2 = Emeklilik Yatırım Fonları (Pension Investment Funds) - 3 = Borsa Yatırım Fonları (Exchange Traded Funds) - 4 = Gayrimenkul Yatırım Fonları (Real Estate Investment Funds) - 5 = Girişim Sermayesi Yatırım Fonları (Venture Capital Investment Funds) **Data Source:** TEFAS BindHistoryInfo API endpoint **Cache TTL:** 30 minutes for performance optimization **Default Date Range:** Last 7 days if not specified parameters: - name: page in: path required: true description: Page number (starts from 1) schema: type: integer minimum: 1 - name: size in: query description: Number of items per page schema: type: integer minimum: 1 maximum: 250 default: 50 - name: fundType in: query description: Fund type (1=Menkul Kıymet, 2=Emeklilik, 3=Borsa, 4=Gayrimenkul, 5=Girişim Sermayesi) schema: type: string enum: - '1' - '2' - '3' - '4' - '5' default: '1' - name: startDate in: query description: Start date in dd.mm.yyyy format (defaults to 7 days ago) schema: type: string pattern: ^[0-9]{2}\.[0-9]{2}\.[0-9]{4}$ example: 01.08.2025 - name: endDate in: query description: End date in dd.mm.yyyy format (defaults to today) schema: type: string pattern: ^[0-9]{2}\.[0-9]{2}\.[0-9]{4}$ example: 16.08.2025 responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/PaginatedFundHistoricalResponse' '400': description: Invalid parameters content: application/json: schema: $ref: '#/components/schemas/APIError' '404': description: Page not found content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/funds-reports/trading-institutions: get: tags: - Trading Reports summary: Get Trading Institutions Statistics description: Retrieves statistics about institutions that trade in TEFAS funds parameters: - name: year in: query required: true description: Year (2000-current year) schema: type: integer minimum: 2000 maximum: 2030 default: 2025 - name: month in: query description: Month (0-12, cannot exceed current month for current year, empty for All) schema: type: integer minimum: 1 maximum: 12 # - name: week # in: query # description: Week (1-53, cannot exceed current week for current year) # schema: # type: integer # minimum: 1 # maximum: 53 responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/TradingInstitutionsResponse' '400': description: Invalid parameters content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/funds/count-by-type: get: tags: - Fund Returns summary: Get Fund Count by Type Statistics description: Retrieves statistics about the number of funds by fund type parameters: - name: year in: query required: true description: Year (2000-current year) schema: type: integer minimum: 2000 maximum: 2030 default: 2025 - name: month in: query description: Month (1-12, cannot exceed current month for current year, empty for All) schema: type: integer minimum: 1 maximum: 12 responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/FundCountByTypeResponse' '400': description: Invalid parameters content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/befas/fund-count-by-fund-type: get: tags: - BEFAS summary: Get BEFAS Fund Count by Fund Type description: | Retrieves BEFAS fund count statistics by fund type with optional time period filtering. **BEFAS (Bireysel Emeklilik Fonları Aracılık Sistemi)** - Individual Pension Funds Brokerage System **Business Rules:** - Month and week parameters are mutually exclusive - Cannot exceed current month/week for current year - Year range: 2000-2030 **Data Source:** https://www.tefas.gov.tr/IstatistikiRaporlar/Befas/FonSayisi.aspx **Cache TTL:** 1 hour for performance optimization parameters: - name: year in: query required: true description: Year for the report data (2000-2030) schema: type: integer minimum: 2000 maximum: 2030 default: 2025 - name: month in: query description: Month for the report data (1-12, cannot exceed current month for current year, mutually exclusive with week) schema: type: integer minimum: 1 maximum: 12 - name: week in: query description: Week for the report data (1-53, cannot exceed current week for current year, mutually exclusive with month) schema: type: integer minimum: 1 maximum: 53 responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/BefasFundCountByFundTypeResponse' '400': description: Invalid parameters content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/befas/member-based-transaction-volume-report: get: tags: - BEFAS summary: Get BEFAS Member-Based Transaction Volume Report description: | Retrieves BEFAS member-based transaction volume report showing trading activity by institutions within the BEFAS system. **BEFAS (Bireysel Emeklilik Fonları Aracılık Sistemi)** - Individual Pension Funds Brokerage System **Business Rules:** - Month and week parameters are mutually exclusive - Cannot exceed current month/week for current year - Year range: 2000-2030 **Data Source:** https://www.tefas.gov.tr/IstatistikiRaporlar/Befas/UyeBazliIslemHacmi.aspx **Cache TTL:** 1 hour for performance optimization parameters: - name: year in: query required: true description: Year for the report data (2000-2030) schema: type: integer minimum: 2000 maximum: 2030 default: 2025 - name: month in: query description: Month for the report data (1-12, cannot exceed current month for current year, mutually exclusive with week) schema: type: integer minimum: 1 maximum: 12 - name: week in: query description: Week for the report data (1-53, cannot exceed current week for current year, mutually exclusive with month) schema: type: integer minimum: 1 maximum: 53 responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/BefasMemberBasedTransactionVolumeReportResponse' '400': description: Invalid parameters content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/funds-reports/total-transaction-volume: get: tags: - Trading Reports summary: Get Total Transaction Volume Report description: Retrieves total transaction volume report for a specified year parameters: - name: year in: query required: true description: Year (2015-current year) schema: type: integer minimum: 2015 maximum: 2030 default: 2025 responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/TotalTransactionVolumeReportResponse' '400': description: Invalid parameters content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/funds-reports/member-based-transaction-volume: get: tags: - Trading Reports summary: Get Member-Based Transaction Volume Report description: Retrieves member-based transaction volume report showing trading activity by institutions and member types within TEFAS funds parameters: - name: year in: query required: true description: Year for the report data (2015-current year) schema: type: integer minimum: 2015 maximum: 2030 default: 2025 - name: month in: query description: Month for the report data (1-12, cannot exceed current month for current year) schema: type: integer minimum: 1 maximum: 12 - name: week in: query description: Week for the report data (1-53, cannot exceed current week for current year and month, mutually exclusive with month) schema: type: integer minimum: 1 maximum: 53 responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/MemberBasedTransactionVolumeReportResponse' '400': description: Invalid parameters content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/funds-reports/fund-based-transaction-volume: get: tags: - Trading Reports summary: Get Fund-Based Transaction Volume Report description: Retrieves fund-based transaction volume report showing trading activity by fund types and individual funds within TEFAS platform parameters: - name: year in: query required: true description: Year for the report data (2015-current year) schema: type: integer minimum: 2015 maximum: 2030 default: 2025 - name: month in: query description: Month for the report data (1-12, cannot exceed current month for current year) schema: type: integer minimum: 1 maximum: 12 - name: week in: query description: Week for the report data (1-53, cannot exceed current week for current year and month, mutually exclusive with month) schema: type: integer minimum: 1 maximum: 53 responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/FundBasedTransactionVolumeReportResponse' '400': description: Invalid parameters content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/funds-reports/fund-type-based-member-stock-balances: get: tags: - Trading Reports summary: Get Fund Type-Based Member Stock Balances Report description: Retrieves member stock balances report grouped by fund type and institution within TEFAS funds parameters: - name: year in: query required: true description: Year for the report data (2015-current year) schema: type: integer minimum: 2015 maximum: 2030 default: 2025 - name: month in: query required: true description: Month for the report data (1-12, cannot exceed current month for current year) schema: type: integer minimum: 1 maximum: 12 responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/FundTypeBasedMemberStockBalancesReportResponse' '400': description: Invalid parameters content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/funds/periodic-top-earners: get: tags: - Trading Reports summary: Get Periodic Top Earning Funds description: | Retrieves periodic top earning funds data showing the best performing funds across different time periods. **Time Periods Included:** - Weekly (Haftalık) - Monthly (Aylık) - Quarterly (Üç Aylık) - Semi-Annually (Altı Aylık) - From Year Beginning (Yıl Başından) - Annual (Yıllık) - Triennial (Üç Yıllık) - Quinquennial (Beş Yıllık) **Data Source:** https://www.tefas.gov.tr responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/PeriodicTopEarnersResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/funds/comparison: get: tags: - Fund Returns summary: Get Fund Comparison Data description: | Retrieves fund comparison data for management fees showing detailed fund information including management fees, performance metrics, and fund characteristics. **Fund Types (API Format):** - YAT = Menkul Kıymet Yatırım Fonları (Securities Investment Funds) - EMK = Emeklilik Fonları (Pension Funds) - BYF = Borsa Yatırım Fonları (Exchange Traded Funds) - GYF = Gayrimenkul Yatırım Fonları (Real Estate Investment Funds) - GSYF = Girişim Sermayesi Yatırım Fonları (Venture Capital Investment Funds) **Status Filters:** - '' (empty) = All funds - '1' = Active funds in TEFAS - '0' = Inactive funds in TEFAS **Data Source:** https://www.tefas.gov.tr/api/DB/BindComparisonManagementFees parameters: - name: fundType in: query description: Fund type (YAT, EMK, BYF, GYF, GSYF) or numeric (1-5 will be converted) schema: type: string enum: - YAT - EMK - BYF - GYF - GSYF - '1' - '2' - '3' - '4' - '5' default: YAT - name: islemDurum in: query description: Fund status filter (empty=All, 1=Active, 0=Inactive) schema: type: string enum: - '' - '0' - '1' default: '' - name: kurucuKod in: query description: | Portfolio management company code (founder code). - Use '*' or leave empty for all companies (default) - Use a valid 3-character company code (e.g., AKP, MUP, ZPY) for specific company **Available Company Codes:** AKP, MUP, PGA, ABO, ZRA, APY, ALA, TLR, GPO, BLP, BVP, EPY, FIP, GRP, FNV, FTP, EUP, HFP, GEP, IGR, IGP, ISY, ISP, KGY, KPO, KTP, LCP, LPO, MAP, MGY, NTR, VVP, NRL, OGP, ORG, OPO, PA1, PRT, IEP, FPY, PIE, ROP, TCR, SKP, KIG, UNP, VPG, KCP, ZPY, YGP schema: type: string default: '*' pattern: ^(\*|[A-Z]{3})$ example: 'AKP' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/FundComparisonResponse' '400': description: Invalid parameters content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/funds/comparison/{page}: get: tags: - Fund Returns summary: Get Fund Comparison Data with Pagination description: | Retrieves fund comparison data with pagination for management fees analysis. **Fund Types (API Format):** - YAT = Menkul Kıymet Yatırım Fonları (Securities Investment Funds) - EMK = Emeklilik Fonları (Pension Funds) - BYF = Borsa Yatırım Fonları (Exchange Traded Funds) - GYF = Gayrimenkul Yatırım Fonları (Real Estate Investment Funds) - GSYF = Girişim Sermayesi Yatırım Fonları (Venture Capital Investment Funds) **Status Filters:** - '' (empty) = All funds - '1' = Active funds in TEFAS - '0' = Inactive funds in TEFAS **Data Source:** https://www.tefas.gov.tr/api/DB/BindComparisonManagementFees parameters: - name: page in: path required: true description: Page number (starts from 0) schema: type: integer minimum: 0 - name: size in: query description: Number of items per page schema: type: integer minimum: 1 maximum: 250 default: 50 - name: fundType in: query description: Fund type (YAT, EMK, BYF, GYF, GSYF) or numeric (1-5 will be converted) schema: type: string enum: - YAT - EMK - BYF - GYF - GSYF - '1' - '2' - '3' - '4' - '5' default: YAT - name: islemDurum in: query description: Fund status filter (empty=All, 1=Active, 0=Inactive) schema: type: string enum: - '' - '0' - '1' default: '' - name: kurucuKod in: query description: | Portfolio management company code (founder code). - Use '*' or leave empty for all companies (default) - Use a valid 3-character company code (e.g., AKP, MUP, ZPY) for specific company schema: type: string default: '*' pattern: ^(\*|[A-Z]{3})$ example: 'AKP' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/PaginatedFundComparisonResponse' '400': description: Invalid parameters content: application/json: schema: $ref: '#/components/schemas/APIError' '404': description: Page not found content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/fund-analysis/batch: get: tags: - Funds summary: Get Batch Fund Analysis (Admin Only) description: | Performs batch analysis of multiple funds using Go-based scraping with ChromeDP. **Authentication Required:** This endpoint requires admin authentication. **Authentication Methods:** 1. **Bearer Token**: Use `Authorization: Bearer ` header 2. **X-Admin-Key Header**: Use `X-Admin-Key: ` header 3. **Query Parameter**: Use `?admin_key=` query parameter **Features:** - Batch processing with configurable batch size (default: 20 funds) - Sequential processing to avoid rate limiting - Cache-first strategy: skips already cached funds - Real-time progress tracking - Comprehensive error handling **Performance:** - Uses single Chrome instance for efficiency - Intelligent cache checking to minimize redundant scraping - Processes only uncached funds - 10-minute TTL for cached results **Cache Strategy:** - Checks Redis cache before processing each fund - Skips funds already in cache - Saves successful results to cache automatically - Returns cache hit efficiency percentage security: - AdminAuth: [] - AdminKey: [] - AdminQueryKey: [] parameters: - name: batchSize in: query description: Number of funds to process in this batch (default 20, max 50) required: false schema: type: integer minimum: 1 maximum: 50 default: 20 responses: '200': description: Batch analysis completed successfully '400': description: Invalid batch size parameter '401': description: Unauthorized - Invalid or missing admin key '403': description: Forbidden - Admin access required '500': description: Internal server error /api/v1/fund-analysis/{code}: get: tags: - Funds summary: Get Single Fund Analysis description: | Retrieves detailed analysis for a single fund using Go-based scraping. **Data Source:** Direct scraping from TEFAS website using ChromeDP **Cache Strategy:** - Checks Redis cache first - If cached and not expired, returns cached data - If not cached or expired, performs fresh scraping - Caches successful results with 10-minute TTL **Response includes:** - Line values for chart visualization - Pie values for composition breakdown - Column values for performance metrics - Top holdings list - Fund profile information - Price indicators - Historical changes parameters: - name: code in: path description: Fund code (e.g., AAK, AFK, YLB) required: true schema: type: string minLength: 1 maxLength: 10 responses: '200': description: Fund analysis retrieved successfully '400': description: Invalid fund code '404': description: Fund not found '500': description: Internal server error /api/v1/fund-analysis/batch-all/start: post: tags: - Funds summary: Start Background Batch Processing (Admin Only) description: | Starts background batch processing of all funds in the system. **Authentication Required:** This endpoint requires admin authentication. **Authentication Methods:** 1. **Bearer Token**: Use `Authorization: Bearer ` header 2. **X-Admin-Key Header**: Use `X-Admin-Key: ` header 3. **Query Parameter**: Use `?admin_key=` query parameter **Features:** - Background processing: runs asynchronously - Processes all funds in sequential batches - Configurable batch size (default: 10 funds per batch) - Automatic retry for zero-value funds - Progress tracking and status monitoring - Cache-first strategy for efficiency **Retry Mechanism:** - Detects funds with zero or near-zero values - First retry: 30 minutes after initial processing - Second retry: 1 hour after first retry - Maximum 2 retries per fund - Persistent zero-value funds are marked and skipped **Progress Tracking:** - Real-time status updates - Successful/failed fund counts - Current batch information - Estimated completion time - Zero-value fund tracking security: - AdminAuth: [] - AdminKey: [] - AdminQueryKey: [] parameters: - name: batchSize in: query description: Number of funds to process per batch (default 10) required: false schema: type: integer minimum: 1 maximum: 50 default: 10 responses: '200': description: Background batch processing started successfully '400': description: Invalid batch size or processing already running '401': description: Unauthorized - Invalid or missing admin key '403': description: Forbidden - Admin access required '500': description: Internal server error /api/v1/fund-analysis/batch-all/stop: post: tags: - Funds summary: Stop Background Batch Processing (Admin Only) description: | Stops currently running background batch processing. **Authentication Required:** This endpoint requires admin authentication. **Authentication Methods:** 1. **Bearer Token**: Use `Authorization: Bearer ` header 2. **X-Admin-Key Header**: Use `X-Admin-Key: ` header 3. **Query Parameter**: Use `?admin_key=` query parameter **Behavior:** - Gracefully stops the background worker - Completes current batch before stopping - Preserves progress information - Cached data remains available - Can be restarted later security: - AdminAuth: [] - AdminKey: [] - AdminQueryKey: [] responses: '200': description: Background batch processing stopped successfully '400': description: No batch processing is currently running '401': description: Unauthorized - Invalid or missing admin key '403': description: Forbidden - Admin access required '500': description: Internal server error /api/v1/fund-analysis/batch-all/status: get: tags: - Funds summary: Get Batch Processing Status (Admin Only) description: | Retrieves current status and progress of background batch processing. **Authentication Required:** This endpoint requires admin authentication. **Authentication Methods:** 1. **Bearer Token**: Use `Authorization: Bearer ` header 2. **X-Admin-Key Header**: Use `X-Admin-Key: ` header 3. **Query Parameter**: Use `?admin_key=` query parameter **Status Information:** - Current status (idle, running, completed, error) - Total funds to process - Processed funds count - Successful/failed counts - Current batch number - Start time and last batch time - Zero-value funds list - Retry information - Next retry time - Persistent zero-value funds **Status Values:** - **idle**: No processing running - **starting**: Initialization phase - **running**: Currently processing - **completed**: Successfully finished - **error**: Processing failed - **stopped**: Manually stopped security: - AdminAuth: [] - AdminKey: [] - AdminQueryKey: [] responses: '200': description: Batch processing status retrieved successfully '401': description: Unauthorized - Invalid or missing admin key '403': description: Forbidden - Admin access required '500': description: Internal server error /api/v1/reset: get: tags: - Utilities summary: Reset Cache (Admin Only) description: | Clears all cached data. This endpoint requires admin authentication. **Authentication Methods:** 1. **Bearer Token**: Use `Authorization: Bearer ` header 2. **X-Admin-Key Header**: Use `X-Admin-Key: ` header 3. **Query Parameter**: Use `?admin_key=` query parameter The ADMIN_SECRET_KEY must be configured via environment variable. security: - AdminAuth: [] - AdminKey: [] - AdminQueryKey: [] responses: '200': description: Cache reset successfully content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' '401': description: Unauthorized - Invalid or missing admin key content: application/json: schema: $ref: '#/components/schemas/APIError' '403': description: Forbidden - Admin access required content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/cache-keys: get: tags: - Utilities summary: Get Cache Keys (Admin Only) description: | Retrieves all cache keys matching the specified pattern. This endpoint requires admin authentication. **Authentication Methods:** 1. **Bearer Token**: Use `Authorization: Bearer ` header 2. **X-Admin-Key Header**: Use `X-Admin-Key: ` header 3. **Query Parameter**: Use `?admin_key=` query parameter **Pattern Examples:** - `*` (default): Returns all cache keys - `fund:*`: Returns all fund-related cache keys - `fund_returns:*`: Returns all fund returns cache keys - `fund_historical:*`: Returns all historical data cache keys - `befas:*`: Returns all BEFAS-related cache keys **Use Cases:** - Cache monitoring and debugging - Understanding cache structure and key patterns - Cache administration and maintenance - Performance analysis and optimization The ADMIN_SECRET_KEY must be configured via environment variable. security: - AdminAuth: [] - AdminKey: [] - AdminQueryKey: [] parameters: - name: pattern in: query required: false description: | Redis key pattern for filtering results. Uses Redis KEYS command pattern matching: - `*` matches any sequence of characters - `?` matches any single character - `[abc]` matches any character in the bracket - `[a-z]` matches any character in the range **Default**: `*` (returns all keys) schema: type: string default: "*" example: "fund:*" responses: '200': description: Cache keys retrieved successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: array items: type: string description: Array of cache keys matching the pattern example: ["fund:ABC", "fund:DEF", "fund_returns:YAT", "fund_historical:2025-11-15"] meta: $ref: '#/components/schemas/Meta' examples: all_keys: summary: All Cache Keys description: Response when no pattern is specified (returns all keys) value: data: ["fund:ABC", "fund:DEF", "fund_returns:YAT", "fund_returns:EMK", "fund_historical:2025-11-15"] meta: { "total": 5 } success: true fund_keys_only: summary: Fund Keys Only description: Response when pattern="fund:*" value: data: ["fund:ABC", "fund:DEF", "fund:XYZ"] meta: { "total": 3 } success: true '400': description: Invalid pattern parameter content: application/json: schema: $ref: '#/components/schemas/APIError' '401': description: Unauthorized - Invalid or missing admin key content: application/json: schema: $ref: '#/components/schemas/APIError' '403': description: Forbidden - Admin access required content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/delete-cache-by-key: get: tags: - Utilities summary: Delete Cache Key (Admin Only) description: | Deletes a specific cache key from Redis. This endpoint requires admin authentication. **Authentication Methods:** 1. **Bearer Token**: Use `Authorization: Bearer ` header 2. **X-Admin-Key Header**: Use `X-Admin-Key: ` header 3. **Query Parameter**: Use `?admin_key=` query parameter **Safety Features:** - Validates key existence before deletion - Returns 404 if key doesn't exist - Logs all deletion activities for audit trail - Prevents accidental deletions with clear error messages **Use Cases:** - Remove stale or corrupted cache entries - Force refresh of specific cached data - Cache maintenance and cleanup - Debugging and troubleshooting **Note:** This operation is irreversible. The cache key and its data will be permanently removed from Redis. The ADMIN_SECRET_KEY must be configured via environment variable. security: - AdminAuth: [] - AdminKey: [] - AdminQueryKey: [] parameters: - name: key in: query required: true description: | The exact cache key to delete from Redis. **Examples:** - `fund:ABC` - Delete specific fund cache - `fund_returns:YAT` - Delete fund returns cache for YAT type - `fund_historical:2025-11-15` - Delete historical data for specific date - `befas:fund-count:2025:11` - Delete BEFAS fund count cache schema: type: string example: "fund:ABC" responses: '200': description: Cache key deleted successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: object properties: message: type: string example: "Cache key deleted successfully" key: type: string description: The deleted cache key example: "fund:ABC" examples: successful_deletion: summary: Successful Key Deletion value: data: message: "Cache key deleted successfully" key: "fund:ABC" success: true '400': description: Missing or invalid key parameter content: application/json: schema: $ref: '#/components/schemas/APIError' examples: missing_key: summary: Missing Key Parameter value: success: false error: "Missing required parameter" details: "Key parameter is required" status: 400 suggestion: "Add ?key= to your request" severity: "medium" '401': description: Unauthorized - Invalid or missing admin key content: application/json: schema: $ref: '#/components/schemas/APIError' '403': description: Forbidden - Admin access required content: application/json: schema: $ref: '#/components/schemas/APIError' '404': description: Cache key not found content: application/json: schema: $ref: '#/components/schemas/APIError' examples: key_not_found: summary: Key Not Found value: success: false error: "Cache key not found" details: "The specified cache key does not exist" status: 404 suggestion: "Use /api/v1/cache-keys to list available keys" severity: "medium" '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/images: post: tags: - Images summary: Upload Image (Admin Only) description: | Upload an image file to the server. Supports common image formats (JPG, PNG, GIF, WebP). **Authentication Required:** This endpoint requires admin authentication. **Authentication Methods:** 1. **Bearer Token**: Use `Authorization: Bearer ` header 2. **X-Admin-Key Header**: Use `X-Admin-Key: ` header 3. **Query Parameter**: Use `?admin_key=` query parameter **Supported Formats:** - JPEG (.jpg, .jpeg) - PNG (.png) - GIF (.gif) - WebP (.webp) **File Size Limit:** 10MB (configurable via IMAGE_MAX_FILE_SIZE environment variable) **Storage:** Files are stored in the configured storage path (default: ./web/images) security: - AdminAuth: [] - AdminKey: [] - AdminQueryKey: [] requestBody: required: true content: multipart/form-data: schema: type: object properties: image: type: string format: binary description: Image file to upload required: - image responses: '201': description: Image uploaded successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: $ref: '#/components/schemas/ImageInfo' '400': description: Invalid request or unsupported file format content: application/json: schema: $ref: '#/components/schemas/APIError' '401': description: Unauthorized - Invalid or missing admin key content: application/json: schema: $ref: '#/components/schemas/APIError' '403': description: Forbidden - Admin access required content: application/json: schema: $ref: '#/components/schemas/APIError' '413': description: File size exceeds maximum allowed size content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' get: tags: - Images summary: List Images (Admin Only) description: | Retrieve a list of all uploaded images with their metadata. **Authentication Required:** This endpoint requires admin authentication. **Authentication Methods:** 1. **Bearer Token**: Use `Authorization: Bearer ` header 2. **X-Admin-Key Header**: Use `X-Admin-Key: ` header 3. **Query Parameter**: Use `?admin_key=` query parameter **Response includes:** - Image ID (UUID) - Original filename - File size - MIME type - Public URL - Upload timestamp (derived from filename) security: - AdminAuth: [] - AdminKey: [] - AdminQueryKey: [] responses: '200': description: List of images retrieved successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/ImageInfo' '401': description: Unauthorized - Invalid or missing admin key content: application/json: schema: $ref: '#/components/schemas/APIError' '403': description: Forbidden - Admin access required content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/images/{filename}: delete: tags: - Images summary: Delete Image (Admin Only) description: | Delete an image file from the server storage. **Authentication Required:** This endpoint requires admin authentication. **Authentication Methods:** 1. **Bearer Token**: Use `Authorization: Bearer ` header 2. **X-Admin-Key Header**: Use `X-Admin-Key: ` header 3. **Query Parameter**: Use `?admin_key=` query parameter **Note:** This operation is irreversible. The image file will be permanently removed from storage. security: - AdminAuth: [] - AdminKey: [] - AdminQueryKey: [] parameters: - name: filename in: path required: true description: The filename of the image to delete (e.g., "uuid_timestamp.jpg") schema: type: string pattern: ^[a-zA-Z0-9_-]+\.(jpg|jpeg|png|gif|webp)$ example: 550e8400-e29b-41d4-a716-446655440000_1692259200.jpg responses: '200': description: Image deleted successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: object nullable: true '400': description: Invalid filename content: application/json: schema: $ref: '#/components/schemas/APIError' '401': description: Unauthorized - Invalid or missing admin key content: application/json: schema: $ref: '#/components/schemas/APIError' '403': description: Forbidden - Admin access required content: application/json: schema: $ref: '#/components/schemas/APIError' '404': description: Image not found content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /company-images/{filename}: get: tags: - Images summary: Serve Image File (Admin Only) description: | Serve an image file directly. This endpoint is used to display/download images. **Authentication Required:** This endpoint requires admin authentication. **Authentication Methods:** 1. **Bearer Token**: Use `Authorization: Bearer ` header 2. **X-Admin-Key Header**: Use `X-Admin-Key: ` header 3. **Query Parameter**: Use `?admin_key=` query parameter **Features:** - Content-Type header automatically set based on file extension - Cache-Control header set for 24 hours (86400 seconds) - Direct file serving for optimal performance **Usage Examples:** - `

` - Direct download: `wget http://localhost:8080/company-images/filename.jpg?admin_key=YOUR_KEY` security: - AdminAuth: [] - AdminKey: [] - AdminQueryKey: [] parameters: - name: filename in: path required: true description: The filename of the image to serve schema: type: string pattern: ^[a-zA-Z0-9_-]+\.(jpg|jpeg|png|gif|webp)$ example: 550e8400-e29b-41d4-a716-446655440000_1692259200.jpg responses: '200': description: Image file served successfully content: image/jpeg: schema: type: string format: binary image/png: schema: type: string format: binary image/gif: schema: type: string format: binary image/webp: schema: type: string format: binary headers: Cache-Control: description: Caching directive schema: type: string example: public, max-age=86400 Content-Type: description: MIME type of the image schema: type: string example: image/jpeg '400': description: Invalid filename content: application/json: schema: $ref: '#/components/schemas/APIError' '401': description: Unauthorized - Invalid or missing admin key content: application/json: schema: $ref: '#/components/schemas/APIError' '403': description: Forbidden - Admin access required content: application/json: schema: $ref: '#/components/schemas/APIError' '404': description: Image not found content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/cron/jobs: post: tags: - Cron Jobs summary: Create a new cron job description: | Create and schedule a new cron job for automated tasks. Requires admin authentication. **Authentication Methods:** 1. **Bearer Token**: Use `Authorization: Bearer ` header 2. **X-Admin-Key Header**: Use `X-Admin-Key: ` header 3. **Query Parameter**: Use `?admin_key=` query parameter The ADMIN_SECRET_KEY must be configured via environment variable. security: - AdminAuth: [] - AdminKey: [] - AdminQueryKey: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CronJobCreateRequest' examples: fund-refresh: summary: Fund Data Refresh Job value: name: fund-data-refresh description: Popüler fonların verilerini günceller schedule: "0 */30 * * * *" serviceType: popular_funds enabled: true health-check: summary: System Health Check Job value: name: system-health-check description: Sistem sağlığını kontrol eder schedule: "0 */5 * * * *" serviceType: check_system_health enabled: true fund-returns: summary: Fund Returns Collection Job value: name: fund-returns-collection description: Retrieves fund returns data with pagination schedule: "0 0 8 * * MON-FRI" serviceType: fund_returns parameters: fundType: "0" page: 0 size: 50 enabled: true responses: '201': description: Cron job created successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: $ref: '#/components/schemas/CronJobResponse' '400': description: Invalid request body or cron expression content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' get: tags: - Cron Jobs summary: List cron jobs description: | Retrieve a list of cron jobs with optional filtering and pagination. Requires admin authentication. **Authentication Methods:** 1. **Bearer Token**: Use `Authorization: Bearer ` header 2. **X-Admin-Key Header**: Use `X-Admin-Key: ` header 3. **Query Parameter**: Use `?admin_key=` query parameter The ADMIN_SECRET_KEY must be configured via environment variable. security: - AdminAuth: [] - AdminKey: [] - AdminQueryKey: [] parameters: - name: status in: query description: Filter by job status required: false schema: $ref: '#/components/schemas/CronJobStatus' - name: enabled in: query description: Filter by enabled status required: false schema: type: boolean - name: page in: query description: Page number for pagination required: false schema: type: integer minimum: 0 default: 0 - name: size in: query description: Number of items per page required: false schema: type: integer minimum: 1 maximum: 100 default: 20 responses: '200': description: List of cron jobs retrieved successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: $ref: '#/components/schemas/CronJobListResponse' '400': description: Invalid query parameters content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/cron/jobs/{id}: get: tags: - Cron Jobs summary: Get cron job by ID description: | Retrieve details of a specific cron job. Requires admin authentication. **Authentication Methods:** 1. **Bearer Token**: Use `Authorization: Bearer ` header 2. **X-Admin-Key Header**: Use `X-Admin-Key: ` header 3. **Query Parameter**: Use `?admin_key=` query parameter The ADMIN_SECRET_KEY must be configured via environment variable. security: - AdminAuth: [] - AdminKey: [] - AdminQueryKey: [] parameters: - name: id in: path description: Job ID required: true schema: type: string format: uuid responses: '200': description: Job retrieved successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: $ref: '#/components/schemas/CronJobResponse' '404': description: Job not found content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' put: tags: - Cron Jobs summary: Update cron job description: | Update an existing cron job's configuration. Requires admin authentication. **Authentication Methods:** 1. **Bearer Token**: Use `Authorization: Bearer ` header 2. **X-Admin-Key Header**: Use `X-Admin-Key: ` header 3. **Query Parameter**: Use `?admin_key=` query parameter The ADMIN_SECRET_KEY must be configured via environment variable. security: - AdminAuth: [] - AdminKey: [] - AdminQueryKey: [] parameters: - name: id in: path description: Job ID required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CronJobUpdateRequest' examples: update-schedule: summary: Update Schedule value: schedule: 0 */15 * * * * disable-job: summary: Disable Job value: enabled: false responses: '200': description: Job updated successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: $ref: '#/components/schemas/CronJobResponse' '400': description: Invalid request body content: application/json: schema: $ref: '#/components/schemas/APIError' '404': description: Job not found content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' delete: tags: - Cron Jobs summary: Delete cron job description: | Delete an existing cron job and stop its execution. Requires admin authentication. **Authentication Methods:** 1. **Bearer Token**: Use `Authorization: Bearer ` header 2. **X-Admin-Key Header**: Use `X-Admin-Key: ` header 3. **Query Parameter**: Use `?admin_key=` query parameter The ADMIN_SECRET_KEY must be configured via environment variable. security: - AdminAuth: [] - AdminKey: [] - AdminQueryKey: [] parameters: - name: id in: path description: Job ID required: true schema: type: string format: uuid responses: '200': description: Job deleted successfully content: application/json: schema: $ref: '#/components/schemas/APIResponse' '404': description: Job not found content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/cron/jobs/{id}/stats: get: tags: - Cron Jobs summary: Get job statistics description: | Retrieve execution statistics and performance metrics for a specific cron job. Requires admin authentication. **Authentication Methods:** 1. **Bearer Token**: Use `Authorization: Bearer ` header 2. **X-Admin-Key Header**: Use `X-Admin-Key: ` header 3. **Query Parameter**: Use `?admin_key=` query parameter The ADMIN_SECRET_KEY must be configured via environment variable. security: - AdminAuth: [] - AdminKey: [] - AdminQueryKey: [] parameters: - name: id in: path description: Job ID required: true schema: type: string format: uuid responses: '200': description: Job statistics retrieved successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: $ref: '#/components/schemas/CronJobStatsResponse' '404': description: Job not found content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/cron/jobs/{id}/executions: get: tags: - Cron Jobs summary: Get job execution history description: | Retrieve execution history for a specific cron job with optional filtering. Requires admin authentication. **Authentication Methods:** 1. **Bearer Token**: Use `Authorization: Bearer ` header 2. **X-Admin-Key Header**: Use `X-Admin-Key: ` header 3. **Query Parameter**: Use `?admin_key=` query parameter The ADMIN_SECRET_KEY must be configured via environment variable. security: - AdminAuth: [] - AdminKey: [] - AdminQueryKey: [] parameters: - name: id in: path description: Job ID required: true schema: type: string format: uuid - name: status in: query description: Filter by execution status required: false schema: $ref: '#/components/schemas/CronJobStatus' - name: from in: query description: Filter executions from this date (RFC3339 format) required: false schema: type: string format: date-time - name: to in: query description: Filter executions until this date (RFC3339 format) required: false schema: type: string format: date-time - name: page in: query description: Page number for pagination required: false schema: type: integer minimum: 0 default: 0 - name: size in: query description: Number of items per page required: false schema: type: integer minimum: 1 maximum: 100 default: 20 responses: '200': description: Job executions retrieved successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: $ref: '#/components/schemas/CronJobExecutionListResponse' '400': description: Invalid query parameters content: application/json: schema: $ref: '#/components/schemas/APIError' '404': description: Job not found content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/cron/service-types: get: tags: - Cron Jobs summary: Get supported service types description: | Retrieve a list of all supported service types for cron job creation. This endpoint is public and doesn't require authentication. This endpoint helps mobile applications and other clients discover available services that can be scheduled as cron jobs. Each service type includes information about its default endpoint, description, and parameter requirements. responses: '200': description: Service types retrieved successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: $ref: '#/components/schemas/ServiceTypeListResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' /api/v1/befas/fund-based-transaction-volume-report: get: tags: - BEFAS summary: Get BEFAS Fund-Based Transaction Volume Report description: | Retrieves BEFAS fund-based transaction volume report data from the Turkish Electronic Fund Trading Platform. This endpoint provides transaction volume analysis by individual funds and fund types, showing: - Top 10 funds by transaction volume with percentages - Transaction volume distribution by fund type categories - Comprehensive metrics for BEFAS fund performance analysis **Data Source**: https://www.tefas.gov.tr/IstatistikiRaporlar/Befas/FonBazliIslemHacmi.aspx **Business Rules:** - `month` and `week` parameters are mutually exclusive - Cannot query future dates (current month/week limits apply) - When both month and week are provided, week takes priority - Data availability depends on TEFAS publishing schedule **Caching**: Results are cached for 1 hour to optimize performance **Rate Limiting**: Subject to API rate limits (if enabled) parameters: - name: year in: query required: true description: | Year for the report data. Must be between 2000 and 2030. Cannot be a future year beyond current year. schema: type: integer minimum: 2000 maximum: 2030 example: 2025 - name: month in: query required: false description: | Month for the report (1-12). Cannot be used together with week parameter. For current year, cannot exceed current month. schema: type: integer minimum: 1 maximum: 12 example: 8 - name: week in: query required: false description: | Week number for the report (1-53). Cannot be used together with month parameter. Takes priority over month if both are provided. For current year, cannot exceed current week. schema: type: integer minimum: 1 maximum: 53 example: 32 responses: '200': description: BEFAS fund-based transaction volume report retrieved successfully content: application/json: schema: $ref: '#/components/schemas/BefasFundBasedTransactionVolumeReportResponse' examples: monthly_report: summary: Monthly report example value: data: by_fund: - fund_code: FND123 transaction_volume: 1500000.5 percentage: 25.5 - fund_code: FND456 transaction_volume: 1200000.75 percentage: 20.4 by_fund_type: - fund_type: Equity Funds transaction_volume: 3000000 percentage: 51 - fund_type: Bond Funds transaction_volume: 2000000.25 percentage: 34 meta: total: 4 success: true message: BEFAS fund-based transaction volume report retrieved successfully weekly_report: summary: Weekly report example value: data: by_fund: - fund_code: ABC100 transaction_volume: 850000.25 percentage: 15.2 by_fund_type: - fund_type: Mixed Funds transaction_volume: 1800000.5 percentage: 32.1 meta: total: 2 success: true message: BEFAS fund-based transaction volume report retrieved successfully '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/APIError' examples: missing_year: summary: Missing required year parameter value: error: Validation failed details: year is required and must be between 2000 and 2030 status: 400 correlationId: req_123456789 suggestion: Please provide a valid year parameter severity: error occurredAt: '2025-08-08T10:30:00Z' conflicting_params: summary: Conflicting month and week parameters value: error: Conflicting parameters details: month and week parameters are mutually exclusive - you can only specify one status: 400 correlationId: req_123456790 suggestion: Please use either month or week parameter, not both severity: error occurredAt: '2025-08-08T10:30:00Z' future_date: summary: Future date validation error value: error: Validation failed details: month cannot be greater than current month for current year status: 400 correlationId: req_123456791 suggestion: Please specify a valid past or current month/week severity: error occurredAt: '2025-08-08T10:30:00Z' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/APIError' examples: rate_limited: summary: Too many requests value: error: Rate limit exceeded details: Too many requests from this IP address status: 429 retryAfter: '2025-08-08T10:31:00Z' correlationId: req_123456792 suggestion: Please wait before making another request severity: warning occurredAt: '2025-08-08T10:30:00Z' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' examples: scraping_error: summary: Data scraping failed value: error: Internal server error details: Failed to scrape data from TEFAS website status: 500 correlationId: req_123456793 suggestion: Please try again later or contact support severity: error occurredAt: '2025-08-08T10:30:00Z' '503': description: Service temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/APIError' examples: service_unavailable: summary: External service unavailable value: error: Service unavailable details: TEFAS website is temporarily unavailable status: 503 correlationId: req_123456794 suggestion: Please try again later severity: warning occurredAt: '2025-08-08T10:30:00Z' /api/v1/befas/total-transaction-volume-report: get: tags: - BEFAS summary: Get BEFAS Total Transaction Volume Report description: | Retrieves BEFAS total transaction volume report data from the Turkish Electronic Fund Trading Platform. This endpoint provides annual transaction volume analysis showing: - Monthly transaction volume breakdown for the specified year - Time series data with total transaction volume, average daily volume, and net settlement amounts - Comprehensive metrics for BEFAS total market analysis **Data Source**: https://www.tefas.gov.tr/IstatistikiRaporlar/Befas/ToplamIslemHacmi.aspx **Business Rules:** - Year range: 2000-2030 - Cannot query future years (current year limit applies) - Data availability depends on TEFAS publishing schedule **Caching**: Results are cached for 1 hour to optimize performance **Rate Limiting**: Subject to API rate limits (if enabled) parameters: - name: year in: query required: true description: | Year for the report data. Must be between 2000 and 2030. Cannot be a future year beyond current year. schema: type: integer minimum: 2000 maximum: 2030 example: 2025 responses: '200': description: BEFAS total transaction volume report retrieved successfully content: application/json: schema: $ref: '#/components/schemas/BefasTotalTransactionVolumeReportResponse' examples: annual_report: summary: Annual report example value: data: - is_total_line: false date: 2025-01 month: 1 year: 2025 total_transaction_volume: 1256068072559.05 average_daily_volume: 41412864323.33 net_settlement_amount: 1256068072559.05 - is_total_line: false date: 2025-02 month: 2 year: 2025 total_transaction_volume: 1180045672234.25 average_daily_volume: 39334855741.14 net_settlement_amount: 1180045672234.25 meta: total: 12 success: true message: BEFAS total transaction volume report retrieved successfully '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/APIError' examples: missing_year: summary: Missing required year parameter value: error: Validation failed details: year is required and must be between 2000 and 2030 status: 400 correlationId: req_123456789 suggestion: Please provide a valid year parameter severity: error occurredAt: '2025-08-08T10:30:00Z' future_year: summary: Future year validation error value: error: Validation failed details: year cannot be greater than current year status: 400 correlationId: req_123456791 suggestion: Please specify a valid past or current year severity: error occurredAt: '2025-08-08T10:30:00Z' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/APIError' examples: rate_limited: summary: Too many requests value: error: Rate limit exceeded details: Too many requests from this IP address status: 429 retryAfter: '2025-08-08T10:31:00Z' correlationId: req_123456792 suggestion: Please wait before making another request severity: warning occurredAt: '2025-08-08T10:30:00Z' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIError' examples: scraping_error: summary: Data scraping failed value: error: Internal server error details: Failed to scrape data from TEFAS website status: 500 correlationId: req_123456793 suggestion: Please try again later or contact support severity: error occurredAt: '2025-08-08T10:30:00Z' '503': description: Service temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/APIError' examples: service_unavailable: summary: External service unavailable value: error: Service unavailable details: TEFAS website is temporarily unavailable status: 503 correlationId: req_123456794 suggestion: Please try again later severity: warning occurredAt: '2025-08-08T10:30:00Z' /api/v1/economic-calendar/events: get: tags: - Economic Calendar summary: List Economic Events description: Retrieve a list of economic calendar events with filtering options. parameters: - name: page in: query schema: type: integer default: 1 - name: limit in: query schema: type: integer default: 50 - name: lang in: query schema: type: string example: "TR" - name: q in: query description: Search query for event name schema: type: string - name: start_date in: query description: Filter by start date (YYYY-MM-DD) schema: type: string format: date responses: '200': description: Successful response content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/EventDetail' count: type: integer page: type: integer limit: type: integer /api/v1/economic-calendar/events/filters: get: tags: - Economic Calendar summary: Get distinct filter parameters operationId: getEconomicCalendarFilterParams responses: '200': description: Distinct filter values content: application/json: schema: $ref: '#/components/schemas/EventFilterParams' /api/v1/economic-calendar/scrape: post: tags: - Economic Calendar summary: Manually trigger the scraper operationId: triggerEconomicCalendarScraper security: - AdminAuth: [] responses: '202': description: Scraper triggered successfully (async) content: application/json: schema: type: object properties: message: type: string example: Scraper triggered successfully /api/v1/economic-calendar/events/search: post: tags: - Economic Calendar summary: Advanced Search for Events description: Search for economic events using complex filters. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EventFilter' responses: '200': description: Successful response content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/EventDetail' count: type: integer page: type: integer limit: type: integer /api/v1/economic-calendar/events/{id}: get: tags: - Economic Calendar summary: Get Event Details description: Retrieve details for a specific economic event. parameters: - name: id in: path required: true schema: type: integer - name: lang in: query schema: type: string responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/EventDetail' components: schemas: Fund: type: object description: Complete fund information with all performance data and profile details properties: code: type: string description: Unique fund identifier code example: YLB title: type: string description: Full fund name example: Yapı Kredi Portföy Likit Fon lineValues: type: array items: $ref: '#/components/schemas/LineValue' description: Time series data for line charts pieValues: type: array items: $ref: '#/components/schemas/PieValue' description: Pie chart data for fund composition columnValues: type: array items: $ref: '#/components/schemas/ColumnValue' description: Column chart data for performance metrics topList: type: array items: $ref: '#/components/schemas/KeyValue' description: Top holdings or performance metrics additionalList: type: array items: $ref: '#/components/schemas/KeyValue' description: Additional fund information priceIndicators: type: array items: $ref: '#/components/schemas/KeyValue' description: Price-related indicators and metrics fundProfile: type: array items: $ref: '#/components/schemas/FundProfile' description: Detailed fund profile information fundChangeHistory: type: array items: $ref: '#/components/schemas/FundChangeHistoryItem' description: Historical changes to fund code and title isTimeLong: type: boolean description: Indicates if the time period is long-term example: false required: - code - title ImageInfo: type: object description: Information about an uploaded image properties: id: type: string format: uuid description: Unique identifier for the image example: 550e8400-e29b-41d4-a716-446655440000 filename: type: string description: Generated filename including timestamp example: 550e8400-e29b-41d4-a716-446655440000_1692259200.jpg path: type: string description: Full file system path to the image example: /app/web/images/550e8400-e29b-41d4-a716-446655440000_1692259200.jpg size: type: integer format: int64 description: File size in bytes example: 2048576 mimeType: type: string description: MIME type of the image enum: - image/jpeg - image/png - image/gif - image/webp example: image/jpeg url: type: string description: Public URL to access the image (requires admin authentication) example: /company-images/550e8400-e29b-41d4-a716-446655440000_1692259200.jpg required: - id - filename - path - size - mimeType - url LineValue: type: object description: Data point for line chart visualization properties: order: type: integer description: Order/sequence number for the data point example: 1 value: type: number format: float description: Numeric value for the data point example: 15.75 date: type: string description: Date associated with the data point example: "2025-01-15" count: type: integer description: Count or frequency associated with the data point example: 100 required: - order - value PieValue: type: object description: Data segment for pie chart visualization properties: name: type: string description: Name/label of the pie chart segment example: "Hisse Senetleri" value: type: number format: float description: Numeric value representing the segment size example: 45.5 required: - name - value ColumnValue: type: object description: Data bar for column/bar chart visualization properties: name: type: string description: Name/label of the column example: "Ocak" value: type: number format: float description: Numeric value for the column height example: 1250000.50 order: type: integer description: Order/sequence number for the column example: 1 required: - name - value - order KeyValue: type: object description: Generic key-value pair for various data representations properties: key: type: string description: The key/identifier example: "risk_rating" value: type: string description: The corresponding value example: "5" required: - key - value FundProfile: type: object properties: label: type: string description: Profile field label example: "Fon Türü" value: type: string description: Profile field value example: "Yatırım Fonu" link: type: string description: Optional link for additional information example: "https://example.com/info" required: - label - value FundChangeHistoryItem: type: object description: Historical changes to fund code and title properties: date: type: string description: Date of the change example: "15.01.2023" oldCode: type: string description: Previous fund code example: "ABC" oldTitle: type: string description: Previous fund title example: "Old Fund Name" newCode: type: string description: New fund code example: "XYZ" newTitle: type: string description: New fund title example: "New Fund Name" required: - date - oldCode - oldTitle - newCode - newTitle FundReturn: type: object properties: fundCode: type: string description: Fund code fundName: type: string description: Fund name category: type: string description: Fund category or umbrella type return1m: type: number nullable: true description: 1-month return percentage return3m: type: number nullable: true description: 3-month return percentage return6m: type: number nullable: true description: 6-month return percentage returnYtd: type: number nullable: true description: Year-to-date return percentage return1y: type: number nullable: true description: 1-year return percentage return3y: type: number nullable: true description: 3-year return percentage return5y: type: number nullable: true description: 5-year return percentage returnByDate: type: number nullable: true description: Return percentage for a specific date range required: - fundCode - fundName FundSize: type: object description: Fund size data with portfolio values and growth metrics properties: fundCode: type: string description: Fund code (FONKODU) example: AKB fundName: type: string description: Fund name (FONUNVAN) example: Akbank Para Piyasası Fonu category: type: string description: Fund category (FONTURACIKLAMA) example: Para Piyasası Fonları owner: type: string description: Fund management company (KURUCUKODU) example: AKB firstValue: type: number nullable: true description: First portfolio value (ILKPORTFOYDEGERI) example: 100000000.50 lastValue: type: number nullable: true description: Last portfolio value (SONPORTFOYDEGERI) example: 150000000.75 sizeChange: type: number nullable: true description: Portfolio size change percentage (PORTBUYUKLUKDEGISIM) example: 25.5 firstShare: type: number nullable: true description: First share count (ILKPAYADEDI) example: 10000000.0 lastShare: type: number nullable: true description: Last share count (SONPAYADEDI) example: 12500000.0 shareChange: type: number nullable: true description: Share count change percentage (PAYADETDEGISIM) example: 25.0 netReturn: type: number nullable: true description: Net return percentage (NETGETIRIORANI) example: 15.75 required: - fundCode - fundName FundHistorical: type: object description: Historical fund data from TEFAS BindHistoryInfo API properties: fund_code: type: string description: Fund identifier code example: AAK fund_name: type: string description: Full fund name example: Allianz Yaşam ve Emeklilik A.Ş. Allianz Aktif Karma Emeklilik Yatırım Fonu price: type: number format: float description: Fund price example: 124.45 share_count: type: number format: float description: Total share count in circulation example: 60000000.0 num_of_participants: type: integer description: Number of participants/investors example: 1500 total_portfolio: type: number format: float description: Total portfolio value example: 125000000.5 borsa_bulletin_price: type: number format: float description: Borsa bulletin price (stock exchange bulletin price) example: 124.50 date: type: string description: Date of the record in YYYY-MM-DD format example: "2025-01-15" required: - fund_code - fund_name - price - share_count - num_of_participants - total_portfolio - borsa_bulletin_price - date Meta: type: object description: Pagination and response metadata properties: page: type: integer description: Current page number (0-based internally, 1-based externally) example: 1 minimum: 0 total: type: integer description: Total number of items example: 150 minimum: 0 size: type: integer description: Number of items per page example: 50 minimum: 0 has_more: type: boolean description: Whether there are more pages available example: true next_page: type: integer description: Next page number (if available) example: 2 minimum: 0 prev_page: type: integer description: Previous page number (if available) example: 0 minimum: 0 total_pages: type: integer description: Total number of pages example: 3 minimum: 0 required: - total APIResponse: type: object description: Standard API response wrapper properties: data: description: Response data (type varies by endpoint) example: {} meta: allOf: - $ref: '#/components/schemas/Meta' - description: Pagination and response metadata (optional) success: type: boolean description: Indicates if the request was successful example: true message: type: string description: Optional message describing the response example: "Data retrieved successfully" required: - data - success FundListResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/KeyValue' Company: type: object description: | Portfolio management company information for Turkish mutual funds. Companies are categorized by the types of funds they manage: - **YAT**: Yatırım Fonları (Investment Funds) - **EMK**: Emeklilik Fonları (Pension Funds) - **BYF**: Borsa Yatırım Fonları (Exchange Traded Funds) - **GYF**: Gayrimenkul Yatırım Fonları (Real Estate Investment Funds) - **GSYF**: Girişim Sermayesi Yatırım Fonları (Venture Capital Investment Funds) **Data Source**: Dynamically scraped from TEFAS dropdown menus properties: code: type: string description: Unique 3-character company identifier code (uppercase) example: "AKP" pattern: ^[A-Z0-9]{3}$ minLength: 3 maxLength: 3 company: type: string description: Official full legal name of the portfolio management company example: "AK PORTFÖY YÖNETİMİ A.Ş." minLength: 1 category: type: string description: Fund type category that this company operates in example: "YAT" enum: - YAT - EMK - BYF - GYF - GSYF required: - code - company - category CompanyResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/Company' FundHistoryData: type: object description: | Historical fund data record from PostgreSQL database. **Data Source:** fund_line_values table **Date Format:** YYYY-MM-DD **Ordering:** Descending by date (newest first) properties: fundCode: type: string description: Fund code identifier example: "YLB" pattern: ^[A-Za-z0-9]{3,6}$ date: type: string format: date description: Date of the fund value (YYYY-MM-DD) example: "2026-01-24" value: type: number format: double description: Fund unit price value example: 1.234567 createdAt: type: string format: date-time description: Timestamp when the record was first created example: "2026-01-24T10:00:00Z" updatedAt: type: string format: date-time description: Timestamp when the record was last updated example: "2026-01-24T10:00:00Z" required: - fundCode - date - value - createdAt - updatedAt FundHistoryResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/FundHistoryData' meta: $ref: '#/components/schemas/Meta' LatestFundDataResponse: type: object description: | Latest fund data for a specific date with automatic weekend handling. **Weekend Handling:** - Saturday → Returns Friday's data - Sunday → Returns Friday's data - Weekday → Returns same day's data **Data Source:** fund_line_values table with SQL-level date adjustment properties: fundCode: type: string description: Fund code identifier example: "YLB" pattern: ^[A-Za-z0-9]{3,6}$ date: type: string format: date description: Date of the fund value (YYYY-MM-DD), may be adjusted for weekends example: "2026-01-24" value: type: number format: double description: Fund unit price value example: 1.234567 createdAt: type: string format: date-time description: Timestamp when the record was first created example: "2026-01-24T10:00:00Z" updatedAt: type: string format: date-time description: Timestamp when the record was last updated example: "2026-01-24T10:00:00Z" required: - fundCode - date - value - createdAt - updatedAt LatestFundDataByDateResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/LatestFundDataResponse' meta: $ref: '#/components/schemas/Meta' message: type: string description: Success message with date and filter information example: "Latest fund data retrieved successfully for date 2026-01-20 (multiple funds)" FundResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: $ref: '#/components/schemas/Fund' FundReturnsResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/FundReturn' PaginatedFundReturnsResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/FundReturn' meta: $ref: '#/components/schemas/Meta' FundReturnsByDateResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/FundReturnsByDate' meta: $ref: '#/components/schemas/Meta' FundReturnsByDateItem: type: object description: Individual fund data for a specific date based on TEFAS BindHistoryInfo API properties: date: type: string description: Date in dd.mm.yyyy format pattern: ^[0-9]{2}\.[0-9]{2}\.[0-9]{4}$ example: 01.01.2024 fund_code: type: string description: Fund code (FONKODU) example: AKL fund_name: type: string description: Fund name (FONUNVAN) example: Akbank Para Piyasası Fonu price: type: number format: float description: Fund price (FIYAT) example: 1.234567 share_count: type: integer format: int64 description: Share count in circulation (TEDPAYSAYISI) example: 15000000 investor_count: type: integer format: int64 description: Number of investors (KISISAYISI) example: 1250 portfolio_size: type: number format: float description: Portfolio size (PORTFOYBUYUKLUK) example: 150000000.5 required: - date - fund_code - fund_name - price - share_count - investor_count - portfolio_size FundReturnsByDate: type: object description: | Fund returns data grouped by fund type with enhanced weekend handling support. **Fund Type Codes:** - **YAT**: Yatırım Fonları (Investment Funds) - **EMK**: Emeklilik Fonları (Pension Funds) - **BYF**: Borsa Yatırım Fonları (Exchange Traded Funds) - **GYF**: Gayrimenkul Yatırım Fonları (Real Estate Investment Funds) - **GSYF**: Girişim Sermayesi Yatırım Fonları (Venture Capital Investment Funds) properties: fund_type: type: string description: Fund type code identifier enum: - YAT - EMK - BYF - GYF - GSYF example: YAT fund_type_name: type: string description: Human-readable fund type name in Turkish example: Yatırım Fonları total: type: integer description: Total number of funds in this fund type category minimum: 0 example: 42 funds: type: array items: $ref: '#/components/schemas/FundReturnsByDateItem' description: Array of individual fund data for this fund type example: [] required: - fund_type - fund_type_name - total - funds FundSizesResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/FundSize' PaginatedFundSizesResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/FundSize' meta: $ref: '#/components/schemas/Meta' FundHistoricalResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/FundHistorical' PaginatedFundHistoricalResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/FundHistorical' meta: $ref: '#/components/schemas/Meta' SuccessResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: object properties: message: type: string TradingInstitutionsResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/TradingInstitution' TradingInstitution: type: object description: Trading institution statistics from TEFAS platform properties: name: type: string description: Name of the trading institution example: "Türkiye Garanti Bankası A.Ş." count: type: number format: float description: Transaction count or volume example: 15750.5 percentage: type: number format: float description: Percentage of total transactions by this institution example: 25.75 minimum: 0 maximum: 100 required: - name - count - percentage APIError: type: object properties: error: type: string details: type: string status: type: integer helpUrl: type: string retryAfter: type: string format: date-time correlationId: type: string documentation: type: string supportContact: type: string suggestion: type: string severity: type: string occurredAt: type: string format: date-time FundCountByTypeResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/FundCountByType' FundCountByType: type: object properties: x: type: number format: double description: X-axis value (category index) 'y': type: number format: double description: Y-axis value (fund count) name: type: string description: Fund type name TotalTransactionVolumeReport: type: object properties: is_total_line: type: boolean description: Indicates if this row is the total line date: type: string description: Year for which the report is generated example: 2025-01 month: type: integer description: Month for which the report is generated example: 1 year: type: integer description: Year for which the report is generated example: 2025 total_transaction_volume: type: number format: double description: Total transaction volume for the specified period example: 1256068072559.05 average_daily_volume: type: number format: double description: Average daily transaction volume example: 41412864323.33 net_settlement_amount: type: number format: double description: Net settlement amount for the specified period example: 1256068072559.05 TotalTransactionVolumeReportResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/TotalTransactionVolumeReport' MemberBasedTransactionVolumeReportByInstitution: type: object required: - institutation_name - transaction_volume - percentage - index properties: index: type: integer description: Index of the institution in the report example: 1 institutation_name: type: string description: Name of the institution example: TÜRKİYE GARANTİ BANKASI A.Ş. transaction_volume: type: number format: double description: Total transaction volume for the institution example: 737190572132.84 percentage: type: number format: double description: Percentage of the total transaction volume represented by the institution example: 12.03 MemberBasedTransactionVolumeReportByMember: type: object required: - member_name - percentage - index properties: member_name: type: string description: Name of the member type example: Üye Tipi Bazında İşlem Hacmi Dağılımı percentage: type: number format: double description: Percentage of the total transaction volume represented by the member type example: 78.93 index: type: integer description: Index of the member in the report example: 1 MemberBasedTransactionVolumeReport: type: object required: - by_institution - by_member properties: by_institution: type: array description: Transaction volume report data grouped by institution items: $ref: '#/components/schemas/MemberBasedTransactionVolumeReportByInstitution' by_member: type: array description: Transaction volume report data grouped by member type items: $ref: '#/components/schemas/MemberBasedTransactionVolumeReportByMember' MemberBasedTransactionVolumeReportResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: $ref: '#/components/schemas/MemberBasedTransactionVolumeReport' meta: allOf: - $ref: '#/components/schemas/Meta' - type: object properties: total: description: Total number of institutions in the report example: 12 FundBasedTransactionVolumeReport: type: object properties: report_date: type: string description: Report generation date in RFC3339 format example: '2025-01-08T10:30:00Z' year: type: integer description: Year of the report data example: 2025 month: type: integer description: Month of the report data (if specified) example: 1 week: type: integer description: Week of the report data (if specified) example: 2 fund_type: type: integer description: Fund type filter applied (if specified) example: 1 by_fund_type: type: array description: Transaction volume report data grouped by fund type items: $ref: '#/components/schemas/FundBasedTransactionVolumeReportByFundType' by_fund: type: array description: Transaction volume report data for individual funds items: $ref: '#/components/schemas/FundBasedTransactionVolumeReportByFund' FundBasedTransactionVolumeReportByFundType: type: object properties: fund_type_name: type: string description: Name of the fund type example: Hisse Senedi Fonları transaction_volume: type: number format: float description: Total transaction volume for this fund type in TL example: 1234567890.5 transaction_count: type: integer description: Total number of transactions for this fund type example: 15678 share: type: number format: float description: Percentage share of total volume example: 25.75 FundBasedTransactionVolumeReportByFund: type: object properties: fund_code: type: string description: TEFAS fund code example: TPB fund_title: type: string description: Full fund name example: Türkiye Petrolleri Portföy Birinci Hisse Senedi Fonu fund_type: type: string description: Fund type category example: Hisse Senedi Fonları transaction_volume: type: number format: float description: Total transaction volume for this fund in TL example: 123456789.25 transaction_count: type: integer description: Total number of transactions for this fund example: 2345 share: type: number format: float description: Percentage share of total volume example: 5.25 FundBasedTransactionVolumeReportResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: $ref: '#/components/schemas/FundBasedTransactionVolumeReport' meta: allOf: - $ref: '#/components/schemas/Meta' - type: object properties: total: description: Total number of funds in the report example: 485 FundTypeBasedMemberStockBalancesReport: type: object properties: code: type: string description: Institution/member code example: ACA institution: type: string description: Name of the institution example: ACAR MENKUL DEĞERLER A.Ş. fund_type: type: string description: Type of the fund example: Hisse Senedi Şemsiye Fonu fund_count: type: integer format: int64 description: Number of fund units held example: 6865405 market_value: type: number format: float description: Market value of holdings in TL example: 5030936.5 FundTypeBasedMemberStockBalancesReportResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/FundTypeBasedMemberStockBalancesReport' meta: allOf: - $ref: '#/components/schemas/Meta' - type: object properties: total: description: Total number of records in the report example: 2347 PeriodicTopEarnersFund: type: object properties: id: type: string description: Fund identifier example: ABC code: type: string description: Fund code example: ABC value: type: number format: double description: Performance value example: 15.75 PeriodicTopEarnersItem: type: object properties: name: type: string description: Fund category name example: Hisse Senedi Fonları funds_count: type: integer description: Number of funds in this category example: 45 sector_volume: type: string description: Sector volume information example: 2.5M 'y': type: number format: double description: Performance value example: 12.35 id: type: string description: Category identifier example: '1' funds: type: array items: $ref: '#/components/schemas/PeriodicTopEarnersFund' description: List of top performing funds in this category PeriodicTopEarnersResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: object properties: weekly: type: array items: $ref: '#/components/schemas/PeriodicTopEarnersItem' description: Weekly top earning funds monthly: type: array items: $ref: '#/components/schemas/PeriodicTopEarnersItem' description: Monthly top earning funds quarterly: type: array items: $ref: '#/components/schemas/PeriodicTopEarnersItem' description: Quarterly top earning funds semiAnnually: type: array items: $ref: '#/components/schemas/PeriodicTopEarnersItem' description: Semi-annually top earning funds fromYearBeginning: type: array items: $ref: '#/components/schemas/PeriodicTopEarnersItem' description: Year-to-date top earning funds annual: type: array items: $ref: '#/components/schemas/PeriodicTopEarnersItem' description: Annual top earning funds triennial: type: array items: $ref: '#/components/schemas/PeriodicTopEarnersItem' description: Triennial top earning funds quinquennial: type: array items: $ref: '#/components/schemas/PeriodicTopEarnersItem' description: Quinquennial top earning funds meta: allOf: - $ref: '#/components/schemas/Meta' - type: object properties: total: description: Total number of items across all periods example: 156 # Cron Job Schemas CronJobStatus: type: string enum: - running - completed - failed - scheduled description: Status of a cron job or execution CronJob: type: object description: Cron job configuration with enhanced service-based execution properties: id: type: string description: Unique job identifier (UUID) example: "550e8400-e29b-41d4-a716-446655440000" name: type: string description: Human-readable job name example: "Daily Fund Returns Collection" description: type: string description: Detailed job description example: "Collects fund returns data every day at 9 AM" schedule: type: string description: Cron expression with seconds support example: "0 0 9 * * MON-FRI" serviceType: $ref: '#/components/schemas/ServiceType' endpoint: type: string description: API endpoint to call example: "/api/v1/funds/returns" parameters: type: object description: Parameters to pass to the service endpoint additionalProperties: true example: fundType: "1" page: 0 size: 100 timeout: type: string description: Request timeout duration (Go duration format) example: "60s" retryCount: type: integer description: Number of retry attempts on failure minimum: 0 maximum: 5 default: 3 status: $ref: '#/components/schemas/CronJobStatus' enabled: type: boolean description: Whether the job is enabled for execution default: true createdAt: type: string format: date-time description: Job creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - id - name - schedule - serviceType - endpoint - status - enabled - createdAt - updatedAt CronJobCreateRequest: type: object description: Request to create a new cron job with enhanced service-based configuration required: - name - schedule - serviceType properties: name: type: string description: Human-readable job name minLength: 3 maxLength: 100 example: "fund-data-refresh" description: type: string description: Detailed job description maxLength: 500 example: "Popüler fonların verilerini günceller" schedule: type: string description: "Cron expression with seconds support (format: second minute hour day month day-of-week)" example: "0 */30 * * * *" serviceType: $ref: '#/components/schemas/ServiceType' endpoint: type: string description: Custom API endpoint (optional - defaults to service type's default endpoint) example: "/api/v1/funds" parameters: type: object description: Parameters to pass to the service endpoint additionalProperties: true example: page: 0 size: 50 timeout: type: string description: Request timeout duration (Go duration format like '60s', '5m') example: "60s" retryCount: type: integer description: Number of retry attempts on failure minimum: 0 maximum: 5 default: 3 enabled: type: boolean description: Whether to enable the job immediately default: true CronJobUpdateRequest: type: object description: Request to update an existing cron job configuration properties: name: type: string description: Updated job name minLength: 3 maxLength: 100 example: "Weekly Fund Returns Collection" description: type: string description: Updated job description maxLength: 500 example: "Collects fund returns data every week" schedule: type: string description: Updated cron expression example: "0 0 9 * * MON" serviceType: $ref: '#/components/schemas/ServiceType' endpoint: type: string description: Updated API endpoint example: "/api/v1/funds/returns" parameters: type: object description: Updated parameters additionalProperties: true example: fundType: "2" size: 50 timeout: type: string description: Updated timeout duration example: "120s" retryCount: type: integer description: Updated retry count minimum: 0 maximum: 5 enabled: type: boolean description: Updated enabled status CronJobExecution: type: object description: Cron job execution record with enhanced metadata tracking properties: id: type: string description: Unique execution identifier example: "exec-550e8400-e29b-41d4-a716-446655440000" jobId: type: string description: Associated job identifier example: "550e8400-e29b-41d4-a716-446655440000" status: $ref: '#/components/schemas/CronJobStatus' startTime: type: string format: date-time description: Execution start timestamp endTime: type: string format: date-time description: Execution end timestamp nullable: true duration: type: string description: Execution duration (Go duration format) example: "2.5s" nullable: true requestParams: type: object description: Request parameters used for the execution additionalProperties: true example: fundType: "1" size: "100" nullable: true statusCode: type: integer description: HTTP status code of the response example: 200 nullable: true responseSize: type: integer description: Size of the response body in bytes example: 15242 nullable: true error: type: string description: Error message if execution failed nullable: true metadata: type: object description: Additional execution metadata including HTTP details additionalProperties: true example: url: "/api/v1/funds/returns?fundType=1&size=100" method: "GET" service_type: "fund-returns" api_success: true data_count: 150 required: - id - jobId - status - startTime CronJobStats: type: object properties: jobId: type: string format: uuid description: ID of the job example: 550e8400-e29b-41d4-a716-446655440000 totalExecutions: type: integer format: int64 description: Total number of executions example: 48 successfulExecutions: type: integer format: int64 description: Number of successful executions example: 46 failedExecutions: type: integer format: int64 description: Number of failed executions example: 2 lastExecution: type: string format: date-time nullable: true description: When the job was last executed example: '2024-01-15T10:30:00Z' nextExecution: type: string format: date-time nullable: true description: When the job will next execute example: '2024-01-15T11:00:00Z' averageDuration: type: string nullable: true description: Average execution duration example: 23.5s successRate: type: number format: float description: Success rate as percentage example: 95.83 lastError: type: string description: Last error message example: '' CronJobResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: $ref: '#/components/schemas/CronJob' CronJobListResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/CronJob' meta: $ref: '#/components/schemas/Meta' CronJobStatsResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: $ref: '#/components/schemas/CronJobStats' CronJobExecutionListResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/CronJobExecution' meta: $ref: '#/components/schemas/Meta' # Service Type Schemas for Cron Jobs ServiceType: type: string enum: # Fund Services - fund_returns - fund_historical_data - popular_funds - fund_comparison_data - fund_sizes - fund_type_totals # BEFAS Services - befas_fund_based_transaction_volume_report - befas_fund_count_by_fund_type - befas_member_based_transaction_volume_report - befas_total_transaction_volume_report # Trading Report Services - trading_institutions_report - fund_type_based_member_stock_balances_report - member_based_transaction_volume_report - total_transaction_volume_report # Fund Analysis Services - fund_returns_by_date - periodic_top_earners - fund_analysis # Utility Services - companies_info - daily_top_funds - monthly_top_funds - weekly_top_funds - upload_image - delete_image - check_system_health description: | Available service types for cron job scheduling. Each service type corresponds to a specific API endpoint that can be called automatically by the cron job system. ServiceTypeInfo: type: object description: Information about a specific service type including its default endpoint and description properties: type: $ref: '#/components/schemas/ServiceType' endpoint: type: string description: Default API endpoint for this service type example: "/api/v1/funds/returns" description: type: string description: Human-readable description of what this service does example: "Retrieve fund returns data with optional filtering and pagination" parameters: type: object description: Example or required parameters for this service additionalProperties: true example: fundType: "0" page: 0 size: 50 method: type: string enum: - GET - POST - PUT - DELETE description: HTTP method used for this service default: GET required: - type - endpoint - description - method ServiceTypeListResponse: type: object description: Response containing list of all supported service types properties: serviceTypes: type: array items: $ref: '#/components/schemas/ServiceTypeInfo' description: List of all available service types for cron job scheduling total: type: integer description: Total number of available service types example: 25 required: - serviceTypes - total # Fund Returns by Date Validation Schemas FundReturnsByDateValidationResult: type: object description: Validation result for fund returns by date requests with weekend handling properties: original_date: type: string description: Original date string from request example: "15.01.2025" parsed_date: type: string format: date-time description: Parsed date in ISO format example: "2025-01-15T00:00:00Z" is_business_day: type: boolean description: Whether the date is a business day example: true is_weekend: type: boolean description: Whether the date is a weekend example: false suggested_action: type: string enum: - proceed - use_previous_business_day - return_empty - return_error description: Recommended action for handling the date example: "proceed" suggested_date: type: string description: Alternative date if needed example: "13.01.2025" nearest_business_day: type: string format: date-time nullable: true description: Nearest business day example: "2025-01-13T00:00:00Z" warning: type: string description: Warning message if any example: "Weekend date provided, using last business day" required: - original_date - parsed_date - is_business_day - is_weekend - suggested_action # Fund Comparison Schemas FundComparison: type: object properties: fundCode: type: string description: Fund code (FONKODU) example: AKB fundName: type: string description: Fund name (FONUNVAN) example: Akbank Portföy Birinci Hisse Senedi Fonu fundTypeCode: type: integer nullable: true description: Fund type code (FONTURKOD) example: 1 category: type: string description: Fund category (FONTURACIKLAMA) example: Hisse Senedi Fonları owner: type: string description: Fund manager/owner (KURUCUKODU) example: AKB managementFeeLabel: type: string description: Management fee label (ALTBASLIK1) example: Yönetim Ücreti (%) applied: type: number nullable: true description: Applied management fee rate (UYGULANANYU1Y) example: 2.5 secondLabel: type: string description: Second label (ALTBASLIK2) example: Son İçtüzük Yıllık Getiri (%) lastValue: type: number nullable: true description: Last internal regulations yearly return (FONICTUZUKYU1G) example: 15.75 yearlyReturn: type: number nullable: true description: Yearly return percentage (YILLIKGETIRI) example: 18.25 thirdLabel: type: string description: Third label (ALTBASLIK3) example: Fon Toplam Gider Kesinti Oranı (%) totalExpenseRatio: type: number nullable: true description: Total expense ratio (FONTOPGIDERKESORAN) example: 3.2 required: - fundCode - fundName FundComparisonResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/FundComparison' PaginatedFundComparisonResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/FundComparison' meta: $ref: '#/components/schemas/Meta' # BEFAS Schemas BefasFundCountByFundType: type: object properties: fund_type: type: string description: Fund type name example: Hisse Senedi Fonu fund_count: type: integer description: Number of funds in this fund type example: 120 required: - fund_type - fund_count BefasFundCountByFundTypeResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/BefasFundCountByFundType' meta: $ref: '#/components/schemas/Meta' BefasMemberBasedTransactionVolumeReport: type: object properties: institution_title: type: string description: Institution name example: Kurum A transaction_volume: type: number format: float description: Transaction volume (TL) example: 1500000.5 percentage: type: number format: float description: Percentage (%) example: 25.5 is_total: type: boolean description: Is it the total row? example: false required: - institution_title - transaction_volume - percentage - is_total BefasMemberBasedTransactionVolumeReportResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/BefasMemberBasedTransactionVolumeReport' meta: $ref: '#/components/schemas/Meta' BefasFundBasedTransactionVolumeReportByFund: type: object description: Transaction volume data for individual funds properties: fund_code: type: string description: Fund identifier code example: FND123 minLength: 1 transaction_volume: type: number format: float description: Total transaction volume in Turkish Lira (TL) example: 1500000.5 minimum: 0 percentage: type: number format: float description: Percentage of total transaction volume example: 25.5 minimum: 0 maximum: 100 required: - fund_code - transaction_volume - percentage BefasFundBasedTransactionVolumeReportByFundType: type: object description: Transaction volume data aggregated by fund types properties: fund_type: type: string description: Fund type category name example: Equity Funds minLength: 1 transaction_volume: type: number format: float description: Total transaction volume for this fund type in Turkish Lira (TL) example: 3000000 minimum: 0 percentage: type: number format: float description: Percentage of total transaction volume for this fund type example: 51 minimum: 0 maximum: 100 required: - fund_type - transaction_volume - percentage BefasFundBasedTransactionVolumeReport: type: object description: | Complete BEFAS fund-based transaction volume report containing both individual fund data and fund type aggregations. This report provides comprehensive transaction volume analysis including: - Individual fund performance rankings (top performers) - Fund type category distributions - Percentage breakdowns for portfolio analysis properties: by_fund: type: array description: Transaction volume data for individual funds (typically top 10 performers) items: $ref: '#/components/schemas/BefasFundBasedTransactionVolumeReportByFund' example: - fund_code: FND123 transaction_volume: 1500000.5 percentage: 25.5 - fund_code: FND456 transaction_volume: 1200000.75 percentage: 20.4 by_fund_type: type: array description: Transaction volume data aggregated by fund types items: $ref: '#/components/schemas/BefasFundBasedTransactionVolumeReportByFundType' example: - fund_type: Equity Funds transaction_volume: 3000000 percentage: 51 - fund_type: Bond Funds transaction_volume: 2000000.25 percentage: 34 required: - by_fund - by_fund_type BefasFundBasedTransactionVolumeReportResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: $ref: '#/components/schemas/BefasFundBasedTransactionVolumeReport' meta: allOf: - $ref: '#/components/schemas/Meta' - type: object properties: total: type: integer description: Total number of data items (by_fund + by_fund_type combined) example: 15 minimum: 0 example: data: by_fund: - fund_code: FND123 transaction_volume: 1500000.5 percentage: 25.5 - fund_code: FND456 transaction_volume: 1200000.75 percentage: 20.4 by_fund_type: - fund_type: Equity Funds transaction_volume: 3000000 percentage: 51 - fund_type: Bond Funds transaction_volume: 2000000.25 percentage: 34 meta: total: 4 success: true message: BEFAS fund-based transaction volume report retrieved successfully BefasTotalTransactionVolumeReport: type: object description: | Individual record of BEFAS total transaction volume report representing monthly data within a specified year. This data structure matches the regular Total Transaction Volume Report but for BEFAS-specific data sources. Each record represents monthly transaction statistics for the BEFAS system. properties: is_total_line: type: boolean description: Indicates if this record represents a total/summary line example: false date: type: string description: Date identifier in YYYY-MM format for the month example: 2025-01 pattern: ^[0-9]{4}-[0-9]{2}$ month: type: integer description: Month number (1-12) example: 1 minimum: 1 maximum: 12 year: type: integer description: Year for which the data is reported example: 2025 minimum: 2000 maximum: 2030 total_transaction_volume: type: number format: float description: Total transaction volume for the month in Turkish Lira (TL) example: 1256068072559.05 minimum: 0 average_daily_volume: type: number format: float description: Average daily transaction volume for the month in Turkish Lira (TL) example: 41412864323.33 minimum: 0 net_settlement_amount: type: number format: float description: Net settlement amount for the month in Turkish Lira (TL) example: 1256068072559.05 minimum: 0 required: - is_total_line - date - month - year - total_transaction_volume - average_daily_volume - net_settlement_amount BefasTotalTransactionVolumeReportResponse: allOf: - $ref: '#/components/schemas/APIResponse' - type: object properties: data: type: array description: Array of monthly BEFAS transaction volume records for the specified year items: $ref: '#/components/schemas/BefasTotalTransactionVolumeReport' example: - is_total_line: false date: 2025-01 month: 1 year: 2025 total_transaction_volume: 1256068072559.05 average_daily_volume: 41412864323.33 net_settlement_amount: 1256068072559.05 - is_total_line: false date: 2025-02 month: 2 year: 2025 total_transaction_volume: 1180045672234.25 average_daily_volume: 39334855741.14 net_settlement_amount: 1180045672234.25 meta: allOf: - $ref: '#/components/schemas/Meta' - type: object properties: total: type: integer description: Total number of monthly records in the report example: 12 minimum: 0 maximum: 12 example: data: - is_total_line: false date: 2025-01 month: 1 year: 2025 total_transaction_volume: 1256068072559.05 average_daily_volume: 41412864323.33 net_settlement_amount: 1256068072559.05 - is_total_line: false date: 2025-02 month: 2 year: 2025 total_transaction_volume: 1180045672234.25 average_daily_volume: 39334855741.14 net_settlement_amount: 1180045672234.25 meta: total: 12 success: true message: BEFAS total transaction volume report retrieved successfully EventDetail: type: object properties: event_id: type: integer category: type: string importance: type: string country_code: type: string currency: type: string occurrence_time: type: string format: date-time actual: type: number previous: type: number forecast: type: number unit: type: string name: type: string description: type: string EventFilter: type: object properties: start_date: type: string format: date-time end_date: type: string format: date-time country_codes: type: array items: type: string currencies: type: array items: type: string importance: type: array items: type: string categories: type: array items: type: string actual_to_forecast: type: array items: type: string search_query: type: string lang: type: string limit: type: integer page: type: integer EventFilterParams: type: object properties: country_codes: type: array items: type: string categories: type: array items: type: string importance: type: array items: type: string currencies: type: array items: type: string securitySchemes: AdminAuth: type: http scheme: bearer bearerFormat: JWT description: Admin authentication using Bearer token. Set ADMIN_SECRET_KEY environment variable and use it as Bearer token. AdminKey: type: apiKey in: header name: X-Admin-Key description: Admin authentication using X-Admin-Key header AdminQueryKey: type: apiKey in: query name: admin_key description: Admin authentication using admin_key query parameter