{"openapi":"3.0.3","info":{"title":"0Wallet Service API","description":"API documentation for Services, Categories, and Providers.\nAll endpoints are gRPC-based (exposed via gRPC-Gateway).\nAuthentication is via PASETO token in the Authorization header.\n\n**Datetime format:** All datetime fields use ISO 8601 / RFC 3339 format with timezone offset.\nUse `+08:00` for Malaysia time (e.g. `\"2026-02-26T00:00:00+08:00\"`).\nResponses return datetime strings with `+08:00` offset. The database stores all timestamps as UTC internally.\n","version":"1.1.0"},"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://virtserver.swaggerhub.com/ndm-637/0WalletServices88/1.0.0"},{"url":"https://api.domain.com","description":"Stag Server"}],"tags":[{"name":"Catalog","description":"Service list, categories, providers, popular and recent"},{"name":"Game","description":"Launch service and restore balance"},{"name":"Bet History","description":"Player bet history records"},{"name":"Bet History (Admin)","description":"Admin bet history query across all users"},{"name":"Promotion (Admin)","description":"Admin CRUD for promotions and player claim records"},{"name":"Promotion (Player)","description":"Player-facing promotion listing and claiming"},{"name":"Promotion Category (Admin)","description":"Admin CRUD for promotion categories"},{"name":"Promotion Category (Player)","description":"Player-facing promotion category listing"},{"name":"Provider Credential (Admin)","description":"Admin CRUD for provider credentials, schema, and connection testing"}],"paths":{"/v1/service/list":{"get":{"tags":["Catalog"],"summary":"Get service list","description":"Retrieve list of services with optional filters","parameters":[{"name":"provider_id","in":"query","description":"Filter by provider ID (optional)","schema":{"type":"integer"},"example":1},{"name":"category_id","in":"query","description":"Filter by category ID (optional)","schema":{"type":"integer"},"example":5},{"name":"status","in":"query","description":"Filter by active status (optional)","schema":{"type":"boolean"},"example":true},{"name":"provider_category_ids","in":"query","description":"Filter by provider category IDs (optional, repeated param).\nPass multiple values as repeated params: ?provider_category_ids=1&provider_category_ids=3&provider_category_ids=5\n","schema":{"type":"array","items":{"type":"integer"}},"style":"form","explode":true,"example":[1,3]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceListResponse"},"example":{"total":251,"services":[{"id":18,"provider_id":1,"provider_name":"jili","name":"Royal Fishing","service_code":"1","category_id":5,"category_name":"Fishing","icon_url":"","status":true,"service_tag":1,"maintenance":false,"provider_category_id":2},{"id":19,"provider_id":1,"provider_name":"jili","name":"Chin Shi Huang","service_code":"2","category_id":3,"category_name":"Slots","icon_url":"","status":true,"service_tag":2,"maintenance":false,"provider_category_id":1}]}}}},"500":{"description":"Internal server error"}}}},"/v1/service/categories":{"get":{"tags":["Catalog"],"summary":"Get categories","description":"Retrieve all service categories","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoriesResponse"},"example":{"total":9,"categories":[{"id":1,"name":"Sports / E-sports","slug":"sports-esports","icon_url":"","status":true},{"id":2,"name":"Live Casino","slug":"live-casino","icon_url":"","status":true}]}}}},"500":{"description":"Internal server error"}}}},"/v1/service/providers":{"get":{"tags":["Catalog"],"summary":"Get providers","description":"Retrieve list of providers","parameters":[{"name":"status","in":"query","description":"Filter providers by active status (optional)","schema":{"type":"boolean"},"example":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderListResponse"},"example":{"total":2,"providers":[{"id":1,"name":"jili","code":"jili","active_icon_url":"","icon_url":"","status":false,"categories":[{"provider_category_id":2,"name":"JILI - FISHING","service_category_id":5,"icon_url":""},{"provider_category_id":1,"name":"JILI - SLOTS","service_category_id":3,"icon_url":""}]}]}}}},"500":{"description":"Internal server error"}}}},"/v1/service/provider-categories":{"get":{"tags":["Catalog"],"summary":"Get provider categories","description":"Retrieve provider categories with optional provider filter","parameters":[{"name":"provider_id","in":"query","description":"Filter by provider ID (optional)","schema":{"type":"integer"},"example":1}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderCategoriesResponse"},"example":{"total":3,"categories":[{"id":1,"name":"JILI - SLOTS","provider_id":1,"service_category_id":3,"category_name":"Slots","status":true,"icon_url":""},{"id":2,"name":"JILI - FISHING","provider_id":1,"service_category_id":5,"category_name":"Fishing","status":true,"icon_url":""}]}}}},"500":{"description":"Internal server error"}}}},"/v1/service/popular":{"get":{"tags":["Catalog"],"summary":"Get popular services","description":"Retrieve most played services ranked by total plays","parameters":[{"name":"limit","in":"query","description":"Max number of results (optional, default 10)","schema":{"type":"integer","default":10},"example":10}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PopularServicesListResponse"},"example":{"total":2,"services":[{"id":18,"provider_id":1,"provider_name":"jili","name":"Royal Fishing","service_code":"1","category_id":5,"category_name":"Fishing","icon_url":"","status":true,"service_tag":1,"maintenance":false,"total_plays":150}]}}}},"500":{"description":"Internal server error"}}}},"/v1/service/recent":{"get":{"tags":["Catalog"],"summary":"Get recent services","description":"Retrieve user's recently played services ordered by last played time.\nRequires authentication (PASETO token).\n","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Max number of results (optional, default 10)","schema":{"type":"integer","default":10},"example":10}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecentServicesListResponse"},"example":{"total":1,"services":[{"id":18,"provider_id":1,"provider_name":"jili","name":"Royal Fishing","service_code":"1","category_id":5,"category_name":"Fishing","icon_url":"","status":true,"service_tag":1,"maintenance":false,"last_played_at":"2026-02-26T00:00:00+08:00"}]}}}},"401":{"description":"Unauthorized - token missing or invalid"},"500":{"description":"Internal server error"}}}},"/v1/service/active-game":{"get":{"tags":["Catalog"],"summary":"Get active game eligibility","description":"Returns the user's current active promotion with allowed provider category and category IDs.\nFrontend uses this to grey out ineligible providers/categories in the game lobby.\nIf no active promotion, `active_game` is null.\nIf `allowed_provider_category_ids` and `allowed_category_ids` are empty, all games are allowed.\nOne user can only have one active promotion at a time.\n","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetActiveGameResponse"},"examples":{"with_promotion":{"summary":"User has active promotion","value":{"active_game":{"promotion_id":1,"promotion_name":"Welcome Bonus","allowed_provider_category_ids":[1,3],"allowed_category_ids":[1]}}},"no_promotion":{"summary":"No active promotion","value":{"active_game":null}}}}}},"401":{"description":"Unauthorized - token missing or invalid"},"500":{"description":"Internal server error"}}}},"/v1/service/launch":{"post":{"tags":["Game"],"summary":"Launch service","description":"Launch a game/service session for the authenticated user.\nUser is identified from the PASETO token. Amount is optional (defaults to full wallet balance for transfer providers).\n","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"description":"Launch service request payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LaunchServiceRequest"},"example":{"service_id":10,"amount":"100.00"}}}},"responses":{"200":{"description":"Launch successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LaunchServiceResponse"},"example":{"login_url":"https://game.jili.com/launch/abc123"}}}},"400":{"description":"Invalid request data"},"401":{"description":"Unauthorized - token missing or invalid"},"500":{"description":"Internal server error"}}}},"/v1/service/restore-balance":{"post":{"tags":["Game"],"summary":"Restore balance","description":"Withdraw balance from provider and credit back to the authenticated user's wallet.\nUser is identified from the PASETO token.\n","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"description":"Restore balance request payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestoreBalanceRequest"},"example":{"provider_id":1}}}},"responses":{"200":{"description":"Balance restored successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestoreBalanceResponse"},"example":{"message":"Balance restored successfully","balance":"120.50"}}}},"400":{"description":"Invalid request data"},"401":{"description":"Unauthorized - token missing or invalid"},"500":{"description":"Internal server error"}}}},"/v1/service/bet-history":{"get":{"tags":["Bet History"],"summary":"Get bet history","description":"Retrieve bet history records for the authenticated user","parameters":[{"name":"start_date","in":"query","description":"Start date filter (YYYY-MM-DD, defaults to 7 days ago)","schema":{"type":"string"},"example":"2026-03-01"},{"name":"end_date","in":"query","description":"End date filter (YYYY-MM-DD, defaults to today)","schema":{"type":"string"},"example":"2026-03-05"},{"name":"limit","in":"query","description":"Max records to return (default 100)","schema":{"type":"integer"},"example":100},{"name":"offset","in":"query","description":"Offset for pagination (default 0)","schema":{"type":"integer"},"example":0}],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Bet history records","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BetHistoryResponse"},"example":{"total":20,"records":[{"theone_id":"831399640","bet_id":"8553_1_831399640000","game_code":"vs20olympgate","game_name":"Gates of Olympus","provider_category_name":"Pragmatic Play","product":"SL","bet_amount":"40.0000","payout_amount":"25.2400","win_loss":"-14.7600","bet_time":"2026-03-03T14:38:28+08:00","settle_time":"2026-03-03T14:40:51+08:00","status":"Y"}]}}}},"401":{"description":"Unauthorized - token missing or invalid"},"500":{"description":"Internal server error"}}}},"/v1/admin/bet-history":{"get":{"tags":["Bet History (Admin)"],"summary":"Get admin bet history","description":"Retrieve bet history records with optional filters.\nIf user_id is not provided, returns all users' bet histories.\n","parameters":[{"name":"start_date","in":"query","description":"Start date filter (YYYY-MM-DD)","schema":{"type":"string"},"example":"2026-03-01"},{"name":"end_date","in":"query","description":"End date filter (YYYY-MM-DD)","schema":{"type":"string"},"example":"2026-03-18"},{"name":"user_id","in":"query","description":"Filter by user ID (optional, omit for all users)","schema":{"type":"string"},"example":"usr_abc123"},{"name":"provider_id","in":"query","description":"Filter by provider ID (optional, omit for all providers)","schema":{"type":"integer","format":"int64"},"example":500001},{"name":"page","in":"query","description":"Page number (default 1)","schema":{"type":"integer"},"example":1},{"name":"page_size","in":"query","description":"Items per page (default 20)","schema":{"type":"integer"},"example":20}],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Admin bet history records with pagination","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AdminBetHistoryResponse"}}},"example":{"data":{"betHistories":[{"user_id":"usr_abc123","provider_id":500001,"bet_id":"8553_1_835905201000","game_code":"vs20olympgold","game_name":"{\"en\":\"Gates of Olympus Super Scatter\",\"zh\":\"奧林帕斯之門\"}","player":"MBR_TOKEN_ABC","round_id":"835905201","meta_options":"{\"product\":\"SL\"}","bet_amount":"10.0000","payout_amount":"15.5000","win_loss":"5.5000","valid_turnover":"10.0000","bet_time":"2026-03-18T16:18:40+08:00","settle_time":"2026-03-18T16:18:50+08:00","status":"Y","is_finished":true}],"pagination":{"page":1,"pageSize":20,"total":150,"totalPages":8}}}}}},"400":{"description":"Bad request - invalid parameters"},"500":{"description":"Internal server error"}}}},"/v1/admin/promotions/create":{"post":{"tags":["Promotion (Admin)"],"summary":"Create promotion","description":"Create a new promotion. Admin authentication required.\nValidates claim_conditions JSON schema based on claim_condition_type.\n","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"description":"Promotion creation payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePromotionRequest"},"example":{"title":"Welcome Bonus 100%","description":"Get 100% bonus on your first deposit","terms_conditions":"Minimum deposit 100. Max bonus 5000.","bonus_type":1,"bonus_value":100,"max_payout":5000,"max_withdrawal":50,"claim_condition_type":1,"claim_conditions":"{\"min_deposit\": 100}","start_date":"","end_date":"2026-04-01T00:00:00+08:00","turnover":20,"winover":0,"provider_category_ids":"[1, 3, 5]","banner_image_url":"https://cdn.example.com/banner.png","promo_image_url":"https://cdn.example.com/promo.png","status":1,"sort_order":0,"promotion_category_id":1,"display_type":1}}}},"responses":{"200":{"description":"Promotion created successfully","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request data"},"401":{"description":"Unauthorized - token missing or invalid"},"500":{"description":"Internal server error"}}}},"/v1/admin/promotions/{id}":{"get":{"tags":["Promotion (Admin)"],"summary":"Get promotion by ID","description":"Retrieve a single promotion by its ID.","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Promotion ID","schema":{"type":"integer","format":"int64"},"example":1}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPromotionResponse"},"example":{"promotion":{"id":1,"title":"Welcome Bonus 100%","description":"Get 100% bonus on your first deposit","terms_conditions":"Minimum deposit 100. Max bonus 5000.","bonus_type":1,"bonus_value":100,"max_payout":5000,"max_withdrawal":50,"claim_condition_type":1,"claim_conditions":"{\"min_deposit\": 100}","start_date":"","end_date":"2026-04-01T00:00:00+08:00","turnover":20,"winover":0,"provider_category_ids":"[1, 3, 5]","banner_image_url":"https://cdn.example.com/banner.png","promo_image_url":"https://cdn.example.com/promo.png","status":1,"sort_order":0,"promotion_category_id":1,"display_type":1,"created_by":"admin-user-id","created_at":"2026-02-26T00:00:00+08:00","updated_at":"2026-02-26T00:00:00+08:00"}}}}},"404":{"description":"Promotion not found"},"500":{"description":"Internal server error"}}},"put":{"tags":["Promotion (Admin)"],"summary":"Update promotion","description":"Update an existing promotion. Only provided/non-empty fields are updated (partial update). Numeric fields (status, max_payout, max_withdrawal, turnover, winover) use null/omit to skip — explicitly sending 0 will update the value to 0.\nAdmin authentication required.\n","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Promotion ID","schema":{"type":"integer","format":"int64"},"example":1}],"requestBody":{"required":true,"description":"Fields to update (only provided/non-empty values are applied; omit a field to leave it unchanged)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePromotionRequest"},"example":{"title":"Welcome Bonus 150%","bonus_value":150,"max_payout":7500,"max_withdrawal":50,"status":1}}}},"responses":{"200":{"description":"Promotion updated successfully","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request data"},"404":{"description":"Promotion not found"},"401":{"description":"Unauthorized - token missing or invalid"},"500":{"description":"Internal server error"}}},"delete":{"tags":["Promotion (Admin)"],"summary":"Delete promotion","description":"Soft-delete a promotion by ID. Admin authentication required.\n","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Promotion ID","schema":{"type":"integer","format":"int64"},"example":1}],"responses":{"200":{"description":"Promotion deleted successfully","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Promotion not found"},"401":{"description":"Unauthorized - token missing or invalid"},"500":{"description":"Internal server error"}}}},"/v1/admin/promotions":{"get":{"tags":["Promotion (Admin)"],"summary":"List promotions (admin)","description":"Paginated list of promotions with search and status filter.\nAdmin authentication required.\n","security":[{"BearerAuth":[]}],"parameters":[{"name":"search","in":"query","description":"Search by title (optional)","schema":{"type":"string"},"example":"Welcome"},{"name":"status","in":"query","description":"Filter by status: 0=inactive, 1=active (optional, omit to return all)","schema":{"type":"integer","enum":[0,1]},"example":1},{"name":"page","in":"query","description":"Page number (min 1)","required":true,"schema":{"type":"integer","minimum":1},"example":1},{"name":"page_size","in":"query","description":"Items per page (1-100, default 20)","required":true,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":20},{"name":"promotion_category_id","in":"query","description":"Filter by promotion category ID (optional, 0 = all)","schema":{"type":"integer","format":"int64"},"example":1}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminPromotionsResponse"},"example":{"promotions":[{"id":1,"title":"Welcome Bonus 100%","description":"Get 100% bonus on your first deposit","bonus_type":1,"bonus_value":100,"max_payout":5000,"max_withdrawal":50,"claim_condition_type":1,"status":1,"sort_order":0,"promotion_category_id":1,"display_type":1,"created_at":"2026-02-26T00:00:00+08:00","updated_at":"2026-02-26T00:00:00+08:00"}],"pagination":{"page":1,"page_size":20,"total":5,"total_pages":1}}}}},"400":{"description":"Invalid request parameters"},"401":{"description":"Unauthorized - token missing or invalid"},"500":{"description":"Internal server error"}}}},"/v1/admin/promotions/condition-template":{"get":{"tags":["Promotion (Admin)"],"summary":"Get claim condition template","description":"Returns the available claim condition fields for a given condition type.\nFrontend uses this to dynamically render a form/dropdown for admin to configure claim conditions.\n`claim_condition_type` is required (1=deposit, 2=free, 3=custom).\n","parameters":[{"in":"query","name":"claim_condition_type","required":true,"schema":{"type":"integer","enum":[1,2,3]},"description":"1 = Deposit\n2 = Free\n3 = Custom\n"}],"responses":{"200":{"description":"Condition template fields","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":0},"success":{"type":"boolean","example":true},"message":{"type":"string","example":""},"data":{"type":"object","properties":{"fields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"The JSON key used in claim_conditions","example":"min_deposit"},"label":{"type":"string","description":"Human-readable label (auto-generated from key)","example":"Min Deposit"},"fieldType":{"type":"string","description":"Input type for frontend rendering","enum":["number","string","boolean","select","multi_input"],"example":"number"},"required":{"type":"boolean","description":"Whether this field is required for the condition type","example":true},"options":{"type":"array","description":"Options for select fields (empty for other types)","items":{"type":"string"},"example":[]}}}}}}}},"examples":{"deposit":{"summary":"Deposit condition (type=1)","value":{"code":0,"success":true,"message":"","data":{"fields":[{"key":"min_deposit","label":"Min Deposit","fieldType":"number","required":true,"options":[]},{"key":"excluded_users","label":"Excluded Users","fieldType":"multi_input","required":false,"options":[]},{"key":"display_description_only","label":"Display Description Only","fieldType":"integer","required":false,"options":[],"description":"0=false, 1=true"},{"key":"display_angpao_text","label":"Display Angpao Text","fieldType":"integer","required":false,"options":[],"description":"0=false, 1=true"},{"key":"claim_time","label":"Claim Time","fieldType":"string","required":false,"options":[]},{"key":"claim_frequency","label":"Claim Frequency","fieldType":"select","required":false,"options":["0:One-time","1:Daily"]},{"key":"credit_less_than","label":"Credit Less Than","fieldType":"number","required":false,"options":[]},{"key":"must_taken_bonus","label":"Must Taken Bonus","fieldType":"number","required":false,"options":[]}]}}}}}}},"400":{"description":"Invalid or missing claim_condition_type","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":3},"success":{"type":"boolean","example":false},"message":{"type":"string","example":"invalid input: invalid claim_condition_type 0"},"data":{"type":"null"}}}}}}}}},"/v1/admin/promotions/records":{"get":{"tags":["Promotion (Admin)"],"summary":"List player promotion records","description":"Paginated list of player promotion claim records with filters and sorting.\nAdmin authentication required.\n","security":[{"BearerAuth":[]}],"parameters":[{"name":"user_id","in":"query","description":"Filter by user ID (optional)","schema":{"type":"string"},"example":"user-123"},{"name":"name","in":"query","description":"Filter by player name (optional)","schema":{"type":"string"}},{"name":"promotion_id","in":"query","description":"Filter by promotion ID (optional)","schema":{"type":"integer","format":"int64"},"example":1},{"name":"promotion_title","in":"query","description":"Filter by promotion title (optional)","schema":{"type":"string"}},{"name":"start_date","in":"query","description":"Filter records from this date (ISO 8601 with +08:00, e.g. 2026-02-26T00:00:00+08:00)","schema":{"type":"string","format":"date-time"}},{"name":"end_date","in":"query","description":"Filter records until this date (ISO 8601 with +08:00, e.g. 2026-05-26T23:59:59+08:00)","schema":{"type":"string","format":"date-time"}},{"name":"sort_by","in":"query","description":"Sort column (optional). Allowed: created_at, user_id, name, promotion_id, promotion_title, target_turnover, current_turnover, bonus_amount, max_withdrawal, status","schema":{"type":"string","enum":["created_at","user_id","name","promotion_id","promotion_title","target_turnover","current_turnover","bonus_amount","max_withdrawal","status"]}},{"name":"sort_order","in":"query","description":"Sort direction (optional)","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"page","in":"query","description":"Page number (min 1)","required":true,"schema":{"type":"integer","minimum":1},"example":1},{"name":"page_size","in":"query","description":"Items per page (1-100, default 20)","required":true,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":20}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListPlayerPromotionRecordsResponse"},"example":{"records":[{"id":1,"promotion_id":1,"promotion_title":"Welcome Bonus 100%","user_id":"user-123","name":"user-123","target_turnover":4000,"current_turnover":1500.5,"bonus_amount":100,"max_withdrawal":5000,"status":1,"claimed_at":"2026-02-26T00:00:00+08:00","completed_at":"","created_at":"2026-02-26T00:00:00+08:00","updated_at":"2026-02-26T20:00:00+08:00"}],"pagination":{"page":1,"page_size":20,"total":12,"total_pages":1}}}}},"401":{"description":"Unauthorized - token missing or invalid"},"500":{"description":"Internal server error"}}}},"/v1/admin/promotions/records/export":{"get":{"tags":["Promotion (Admin)"],"summary":"Export player promotion records (CSV)","description":"Export player promotion claim records as CSV. Same filters as list endpoint (no pagination).\nAdmin authentication required.\n","security":[{"BearerAuth":[]}],"parameters":[{"name":"user_id","in":"query","description":"Filter by user ID (optional)","schema":{"type":"string"}},{"name":"name","in":"query","description":"Filter by player name (optional)","schema":{"type":"string"}},{"name":"promotion_id","in":"query","description":"Filter by promotion ID (optional)","schema":{"type":"integer","format":"int64"}},{"name":"promotion_title","in":"query","description":"Filter by promotion title (optional)","schema":{"type":"string"}},{"name":"start_date","in":"query","description":"Filter records from this date (ISO 8601 with +08:00, e.g. 2026-02-26T00:00:00+08:00)","schema":{"type":"string","format":"date-time"}},{"name":"end_date","in":"query","description":"Filter records until this date (ISO 8601 with +08:00, e.g. 2026-05-26T23:59:59+08:00)","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"CSV data returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportPlayerPromotionRecordsResponse"},"example":{"csv_data":"SUQsUHJvbW90aW9uIElELC4uLg=="}}}},"401":{"description":"Unauthorized - token missing or invalid"},"500":{"description":"Internal server error"}}}},"/v1/promotions":{"get":{"tags":["Promotion (Player)"],"summary":"List active promotions","description":"Retrieve all currently active promotions visible to players.\nOptionally filter by category. No authentication required.\n","parameters":[{"name":"promotion_category_id","in":"query","description":"Filter by promotion category ID (optional, 0 = all)","schema":{"type":"integer","format":"int64"},"example":1}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromotionsResponse"},"example":{"promotions":[{"id":1,"title":"Welcome Bonus 100%","description":"Get 100% bonus on your first deposit","terms_conditions":"Minimum deposit 100. Max bonus 5000.","bonus_type":1,"bonus_value":100,"max_payout":5000,"max_withdrawal":50,"claim_condition_type":1,"claim_conditions":"{\"min_deposit\": 100}","start_date":"","end_date":"2026-04-01T00:00:00+08:00","turnover":20,"winover":0,"provider_category_ids":"[1, 3, 5]","banner_image_url":"https://cdn.example.com/banner.png","promo_image_url":"https://cdn.example.com/promo.png","status":1,"sort_order":0,"promotion_category_id":1,"min_topup_amount":0,"max_topup_amount":0,"min_times_of_topup":0,"claim_limit":0,"claim_reset":0,"initial_free_limit":0,"deposit_free_limit":0,"display_type":1,"display_description_only":false,"display_angpao_text":false,"promotion_category_name":"Welcome Bonus","turnover_winover_type":1,"created_by":"","created_at":"2026-02-26T00:00:00+08:00","updated_at":"2026-02-26T00:00:00+08:00","is_clearable":false,"is_claimable":true}]}}}},"500":{"description":"Internal server error"}}}},"/v1/promotions/{promotion_id}/claim":{"post":{"tags":["Promotion (Player)"],"summary":"Claim a promotion","description":"Claim a promotion for the authenticated player. Flow:\n1. Validates promotion is active and not expired\n2. Checks player has not already claimed this promotion\n3. Validates claim eligibility (e.g. minimum deposit for deposit-type conditions)\n4. Calculates bonus (percentage of balance or fixed amount, capped at max_payout)\n5. Debits player real_bal to 0 and credits bonus_bal (real_bal + bonus)\n6. Creates bonus record with wagering requirement (turnover x bonus_bal) and max_withdrawal cap\n7. Creates a PlayerPromotionRecord with target turnover\n\nAfter claiming, player must meet wagering requirement (bonus_bal >= wagering_required).\nUpon meeting the requirement, max_withdrawal amount is converted to real_bal and remaining bonus_bal is forfeited.\n\nUser is identified from the PASETO token.\n","security":[{"BearerAuth":[]}],"parameters":[{"name":"promotion_id","in":"path","required":true,"description":"Promotion ID to claim","schema":{"type":"integer","format":"int64"},"example":1}],"responses":{"200":{"description":"Promotion claimed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimPromotionResponse"},"example":{"record_id":42,"bonus_amount":100,"message":"Promotion claimed successfully. Bonus: 100.00, Target turnover: 4000.00"}}}},"400":{"description":"Invalid request. Possible reasons:\n- user not authenticated\n- promotion is not active\n- promotion has expired\n- promotion has not started yet\n- you have already claimed this promotion\n- insufficient balance / minimum deposit required\n"},"404":{"description":"Promotion not found"},"401":{"description":"Unauthorized - token missing or invalid"},"500":{"description":"Internal server error"}}}},"/v1/admin/promotion-categories/create":{"post":{"tags":["Promotion Category (Admin)"],"summary":"Create promotion category","description":"Create a new promotion category. Admin authentication required.\n","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"description":"Promotion category creation payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePromotionCategoryRequest"},"example":{"name":"Welcome Bonus","description":"Welcome bonus promotions for new players","sort_order":0,"banner_url":"https://cdn.example.com/category-banner.png","status":1}}}},"responses":{"200":{"description":"Promotion category created successfully","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request data"},"401":{"description":"Unauthorized - token missing or invalid"},"500":{"description":"Internal server error"}}}},"/v1/admin/promotion-categories/{id}":{"get":{"tags":["Promotion Category (Admin)"],"summary":"Get promotion category by ID","description":"Retrieve a single promotion category by its ID.","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Promotion category ID","schema":{"type":"integer","format":"int64"},"example":1}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPromotionCategoryResponse"},"example":{"category":{"id":1,"name":"Welcome Bonus","description":"Welcome bonus promotions for new players","sort_order":0,"banner_url":"https://cdn.example.com/category-banner.png","status":1,"created_at":"2026-02-26T00:00:00+08:00","updated_at":"2026-02-26T00:00:00+08:00"}}}}},"404":{"description":"Promotion category not found"},"500":{"description":"Internal server error"}}},"put":{"tags":["Promotion Category (Admin)"],"summary":"Update promotion category","description":"Update an existing promotion category. Only provided/non-empty fields are updated (partial update). Numeric fields (status, max_payout, max_withdrawal, turnover, winover) use null/omit to skip — explicitly sending 0 will update the value to 0.\nAdmin authentication required.\n","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Promotion category ID","schema":{"type":"integer","format":"int64"},"example":1}],"requestBody":{"required":true,"description":"Fields to update (only provided/non-empty values are applied; omit a field to leave it unchanged)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePromotionCategoryRequest"},"example":{"name":"Hot Promotion","sort_order":1}}}},"responses":{"200":{"description":"Promotion category updated successfully","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request data"},"404":{"description":"Promotion category not found"},"401":{"description":"Unauthorized - token missing or invalid"},"500":{"description":"Internal server error"}}},"delete":{"tags":["Promotion Category (Admin)"],"summary":"Delete promotion category","description":"Soft-delete a promotion category by ID. Admin authentication required.\n","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Promotion category ID","schema":{"type":"integer","format":"int64"},"example":1}],"responses":{"200":{"description":"Promotion category deleted successfully","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Promotion category not found"},"401":{"description":"Unauthorized - token missing or invalid"},"500":{"description":"Internal server error"}}}},"/v1/admin/promotion-categories":{"get":{"tags":["Promotion Category (Admin)"],"summary":"List promotion categories (admin)","description":"Paginated list of promotion categories with search and status filter.\nAdmin authentication required.\n","security":[{"BearerAuth":[]}],"parameters":[{"name":"search","in":"query","description":"Search by category name (optional)","schema":{"type":"string"},"example":"Welcome"},{"name":"status","in":"query","description":"Filter by status: 0=inactive, 1=active (optional, omit to return all)","schema":{"type":"integer","enum":[0,1]},"example":1},{"name":"page","in":"query","description":"Page number (min 1)","required":true,"schema":{"type":"integer","minimum":1},"example":1},{"name":"page_size","in":"query","description":"Items per page (1-100, default 20)","required":true,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":20}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminPromotionCategoriesResponse"},"example":{"categories":[{"id":1,"name":"Welcome Bonus","description":"Welcome bonus promotions for new players","sort_order":0,"banner_url":"https://cdn.example.com/category-banner.png","status":1,"created_at":"2026-02-26T00:00:00+08:00","updated_at":"2026-02-26T00:00:00+08:00"},{"id":2,"name":"Hot Promotion","description":"Hot promotions and special events","sort_order":1,"banner_url":"","status":1,"created_at":"2026-02-26T00:00:00+08:00","updated_at":"2026-02-26T00:00:00+08:00"}],"pagination":{"page":1,"page_size":20,"total":2,"total_pages":1}}}}},"400":{"description":"Invalid request parameters"},"401":{"description":"Unauthorized - token missing or invalid"},"500":{"description":"Internal server error"}}}},"/v1/promotion-categories":{"get":{"tags":["Promotion Category (Player)"],"summary":"List active promotion categories","description":"Retrieve all currently active promotion categories visible to players.\nNo authentication required. Ordered by sort_order ASC.\n","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromotionCategoriesResponse"},"example":{"categories":[{"id":1,"name":"Welcome Bonus","description":"Welcome bonus promotions for new players","sort_order":0,"banner_url":"https://cdn.example.com/category-banner.png","status":1,"created_at":"2026-02-26T00:00:00+08:00","updated_at":"2026-02-26T00:00:00+08:00"},{"id":2,"name":"Hot Promotion","description":"Hot promotions and special events","sort_order":1,"banner_url":"","status":1,"created_at":"2026-02-26T00:00:00+08:00","updated_at":"2026-02-26T00:00:00+08:00"}]}}}},"500":{"description":"Internal server error"}}}},"/v1/service/provider-credentials/providers":{"get":{"tags":["Provider Credential (Admin)"],"summary":"List providers with credential info","description":"Returns all providers with their credential schema, categories, and configuration status.\nOptionally filter by provider_id to get a single provider.\n","security":[{"BearerAuth":[]}],"parameters":[{"name":"provider_id","in":"query","required":false,"schema":{"type":"integer","format":"int64"},"description":"Optional provider ID to filter for a single provider","example":1}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetProviderCredentialListResponse"},"example":{"items":[{"provider_id":1,"provider_code":"JILI","provider_name":"JILI","credential_fields":[{"key":"agent_id","label":"Agent ID","type":"text","required":true},{"key":"agent_key","label":"Agent Key","type":"secret","required":true}],"provider_categories":[{"id":1,"name":"JILI - SLOTS","status":true},{"id":2,"name":"JILI - FISHING","status":true}],"has_credentials":false,"status":false},{"provider_id":2,"provider_code":"FUMA","provider_name":"FUMA","credential_fields":[{"key":"agent_id","label":"Agent ID","type":"text","required":true},{"key":"secret_key","label":"Secret Key","type":"secret","required":true}],"provider_categories":[{"id":3,"name":"FUMA - SLOTS","status":true}],"has_credentials":true,"status":true}]}}}},"500":{"description":"Internal server error"}}}},"/v1/service/provider-credentials":{"post":{"tags":["Provider Credential (Admin)"],"summary":"Save provider credentials","description":"Create or update (upsert) encrypted credentials for a provider.\nValidates against the provider's credential_schema, encrypts values, and auto-runs a connection test if available.\n","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveProviderCredentialRequest"},"example":{"provider_id":1,"api_url":"https://api.jili.com/v1","credential_fields":"{\"agent_id\":\"AG123\",\"agent_key\":\"secret-key-here\"}","status":true,"env":"staging","kiosk_url":"","kiosk_username":"","kiosk_password":"","remark":"","provider_categories":[{"category_id":1,"status":true},{"category_id":2,"status":false}]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveProviderCredentialResponse"},"example":{"success":true,"is_valid":true,"message":"Credentials saved and connection verified"}}}},"400":{"description":"Invalid argument (provider_id or credentials missing, invalid JSON, validation failed)"},"500":{"description":"Internal server error"}}}},"/v1/service/provider-credentials/status/{provider_id}":{"get":{"tags":["Provider Credential (Admin)"],"summary":"Get credential configuration status","description":"Returns credential configuration status. Does NOT return credential values.\n- With `provider_id`: returns status for that specific provider.\n- Without `provider_id` (`/status`): returns status for all configured providers.\n- Optional `status` query param to filter by active/inactive.\n","security":[{"BearerAuth":[]}],"parameters":[{"name":"provider_id","in":"path","required":false,"schema":{"type":"integer","format":"int64"},"description":"Provider ID (optional, omit to get all configured providers)","example":1},{"name":"status","in":"query","required":false,"schema":{"type":"boolean"},"description":"Optional filter: true = active only, false = inactive only, omit = all"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetProviderCredentialStatusResponse"},"examples":{"single_provider":{"summary":"Single provider","value":{"items":[{"provider_id":1,"provider_code":"JILI","provider_name":"JILI","configured":true,"api_url":"https://api.jili.com/v1","status":true,"is_valid":true,"is_whitelist":false,"need_topup":false,"env":"staging","kiosk_url":"","kiosk_username":"","has_kiosk_password":false,"remark":"","updated_at":"2026-03-16T12:00:00+08:00","verified_at":"2026-03-16T12:00:00+08:00","field_keys":["agent_id","agent_key"]}]}},"all_providers":{"summary":"All providers","value":{"items":[{"provider_id":1,"provider_code":"JILI","provider_name":"JILI","configured":true,"api_url":"https://api.jili.com/v1","status":true,"is_valid":true,"is_whitelist":false,"need_topup":false,"env":"staging","has_kiosk_password":false,"remark":"","updated_at":"2026-03-16T12:00:00+08:00","verified_at":"2026-03-16T12:00:00+08:00","field_keys":["agent_id","agent_key"]},{"provider_id":2,"provider_code":"FUMA","provider_name":"FUMA","configured":true,"api_url":"https://api.fuma.com","status":false,"is_valid":false,"is_whitelist":true,"need_topup":true,"env":"staging","has_kiosk_password":false,"remark":"","updated_at":"2026-03-15T10:00:00+08:00","verified_at":"","field_keys":["api_key"]}]}}}}}},"500":{"description":"Internal server error"}}}},"/v1/service/provider-credentials/test-connection":{"post":{"tags":["Provider Credential (Admin)"],"summary":"Test provider connection","description":"Decrypts stored credentials and runs a live connection test against the provider.\nUpdates `is_valid` and `verified_at` based on the result.\n","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider_id"],"properties":{"provider_id":{"type":"integer","format":"int64","description":"Provider ID","example":1}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestProviderConnectionResponse"},"example":{"success":true,"message":"Connected successfully","latency_ms":142}}}},"400":{"description":"Invalid argument (provider_id is required)"},"500":{"description":"Internal server error (no credentials configured, decryption failed, etc.)"}}}},"/v1/service/provider-credentials/values/{provider_id}":{"get":{"tags":["Provider Credential (Admin)"],"summary":"Get decrypted credential values","description":"Returns decrypted credential values with secret fields masked (e.g. `******22f0`).\n- With `provider_id`: returns values for that specific provider.\n- Without `provider_id` (`/values`): returns values for all configured providers.\n- Optional `status` query param to filter by active/inactive.\n","security":[{"BearerAuth":[]}],"parameters":[{"name":"provider_id","in":"path","required":false,"schema":{"type":"integer","format":"int64"},"description":"Provider ID (optional, omit to get all configured providers)","example":1},{"name":"status","in":"query","required":false,"schema":{"type":"boolean"},"description":"Optional filter: true = active only, false = inactive only, omit = all"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetProviderCredentialValuesResponse"},"examples":{"single_provider":{"summary":"Single provider","value":{"items":[{"provider_id":1,"provider_code":"JILI","provider_name":"JILI","api_url":"https://api.jili.com/v1","credential_fields":{"agent_id":"AG123","agent_key":"******here"},"status":true,"is_valid":true,"is_whitelist":false,"need_topup":false,"env":"staging","kiosk_url":"","kiosk_username":"","kiosk_password":"","remark":"","verified_at":"2026-03-16T12:00:00+08:00","provider_categories":[{"id":1,"name":"JILI - SLOTS","status":true},{"id":2,"name":"JILI - FISHING","status":true}]}]}},"all_providers":{"summary":"All providers","value":{"items":[{"provider_id":1,"provider_code":"JILI","provider_name":"JILI","api_url":"https://api.jili.com/v1","credential_fields":{"agent_id":"AG123","agent_key":"******here"},"status":true,"is_valid":true,"is_whitelist":false,"need_topup":false,"env":"staging","kiosk_url":"","kiosk_username":"","kiosk_password":"","remark":"","verified_at":"2026-03-16T12:00:00+08:00","provider_categories":[{"id":1,"name":"JILI - SLOTS","status":true},{"id":2,"name":"JILI - FISHING","status":true}]},{"provider_id":2,"provider_code":"FUMA","provider_name":"FUMA","api_url":"https://api.fuma.com","credential_fields":{"api_key":"******abcd"},"status":false,"is_valid":false,"is_whitelist":true,"need_topup":true,"env":"staging","kiosk_url":"","kiosk_username":"","kiosk_password":"","remark":"","verified_at":"","provider_categories":[{"id":3,"name":"FUMA - LIVE CASINO","status":true}]}]}}}}}},"500":{"description":"Internal server error"}}}},"/v1/service/provider-categories/{category_id}/status":{"put":{"tags":["Provider Credential (Admin)"],"summary":"Enable or disable a provider category","description":"Toggle the status of a provider category (enable/disable).\n","security":[{"BearerAuth":[]}],"parameters":[{"name":"category_id","in":"path","required":true,"schema":{"type":"integer","format":"int64"},"description":"Provider category ID","example":1}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"boolean","description":"Enable (true) or disable (false) the category","example":true}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCategoryStatusResponse"},"example":{"success":true,"message":"Category enabled"}}}},"400":{"description":"Invalid argument (category_id is required)"},"500":{"description":"Internal server error"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"PASETO token"}},"schemas":{"ServiceListResponse":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of services","example":251},"services":{"type":"array","description":"List of services","items":{"$ref":"#/components/schemas/ServiceItem"}}}},"ServiceItem":{"type":"object","properties":{"id":{"type":"integer","description":"Service ID","example":18},"provider_id":{"type":"integer","description":"Provider ID","example":1},"provider_name":{"type":"string","description":"Provider name","example":"jili"},"name":{"type":"string","description":"Service name","example":"Royal Fishing"},"service_code":{"type":"string","description":"Service internal code","example":"1"},"category_id":{"type":"integer","description":"Category ID","example":5},"category_name":{"type":"string","description":"Category name","example":"Fishing"},"rtp":{"type":"string","nullable":true,"description":"Return to Player (optional)","example":"96.5"},"icon_url":{"type":"string","description":"Service icon URL","example":""},"status":{"type":"boolean","description":"Service active status","example":true},"service_tag":{"type":"integer","nullable":true,"description":"Service tag (0=none, 1=hot, 2=new)","enum":[0,1,2],"example":1},"maintenance":{"type":"boolean","description":"Maintenance status","example":false},"provider_category_id":{"type":"integer","nullable":true,"description":"Provider category ID (used to match promotion eligibility)","example":1}}},"CategoriesResponse":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of categories","example":9},"categories":{"type":"array","description":"Category list","items":{"$ref":"#/components/schemas/CategoryItem"}}}},"CategoryItem":{"type":"object","properties":{"id":{"type":"integer","description":"Category ID","example":1},"name":{"type":"string","description":"Category name","example":"Sports / E-sports"},"slug":{"type":"string","description":"Category slug","example":"sports-esports"},"icon_url":{"type":"string","description":"Category icon URL","example":""},"status":{"type":"boolean","description":"Category active status","example":true}}},"ProviderListResponse":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of providers","example":2},"providers":{"type":"array","description":"Provider list","items":{"$ref":"#/components/schemas/ProviderItem"}}}},"ProviderItem":{"type":"object","properties":{"id":{"type":"integer","description":"Provider ID","example":1},"name":{"type":"string","description":"Provider name","example":"jili"},"code":{"type":"string","description":"Provider code","example":"jili"},"active_icon_url":{"type":"string","description":"Provider active state icon URL","example":""},"icon_url":{"type":"string","description":"Provider icon URL","example":""},"status":{"type":"boolean","description":"Provider active status","example":false},"categories":{"type":"array","description":"Provider categories","items":{"$ref":"#/components/schemas/ProviderCategoryItem"}}}},"ProviderCategoryItem":{"type":"object","properties":{"provider_category_id":{"type":"integer","description":"Provider category ID","example":2},"name":{"type":"string","description":"Category name under provider","example":"JILI - FISHING"},"service_category_id":{"type":"integer","description":"Related service category ID","example":5},"icon_url":{"type":"string","description":"Category icon URL","example":""}}},"ProviderCategoriesResponse":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of provider categories","example":3},"categories":{"type":"array","description":"List of provider categories","items":{"$ref":"#/components/schemas/ProviderCategoryDetailItem"}}}},"ProviderCategoryDetailItem":{"type":"object","properties":{"id":{"type":"integer","description":"Provider category ID","example":1},"name":{"type":"string","description":"Provider category name","example":"JILI - SLOTS"},"provider_id":{"type":"integer","description":"Provider ID","example":1},"service_category_id":{"type":"integer","description":"Related service category ID","example":3},"category_name":{"type":"string","description":"Service category name","example":"Slots"},"status":{"type":"boolean","description":"Active status","example":true},"icon_url":{"type":"string","description":"Provider category icon URL","example":""}}},"PopularServicesListResponse":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of popular services","example":10},"services":{"type":"array","description":"List of popular services","items":{"$ref":"#/components/schemas/PopularServiceItem"}}}},"PopularServiceItem":{"allOf":[{"$ref":"#/components/schemas/ServiceItem"},{"type":"object","properties":{"total_plays":{"type":"integer","format":"int64","description":"Total play count across all users","example":150}}}]},"RecentServicesListResponse":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of recent services","example":5},"services":{"type":"array","description":"List of recently played services","items":{"$ref":"#/components/schemas/RecentServiceItem"}}}},"RecentServiceItem":{"allOf":[{"$ref":"#/components/schemas/ServiceItem"},{"type":"object","properties":{"last_played_at":{"type":"string","format":"date-time","description":"Last play datetime (ISO 8601 with +08:00)","example":"2026-02-26T00:00:00+08:00"}}}]},"GetActiveGameResponse":{"type":"object","properties":{"active_game":{"nullable":true,"description":"Active promotion info. Null if no active promotion.","allOf":[{"$ref":"#/components/schemas/ActiveGameInfo"}]}}},"ActiveGameInfo":{"type":"object","properties":{"promotion_id":{"type":"integer","format":"int64","description":"Promotion ID","example":1},"promotion_name":{"type":"string","description":"Promotion display name","example":"Welcome Bonus"},"allowed_provider_category_ids":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Allowed provider category IDs. Empty means all allowed.","example":[1,3]},"allowed_category_ids":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Allowed service category IDs (derived from provider categories). Empty means all allowed.","example":[1]}}},"LaunchServiceRequest":{"type":"object","required":["service_id"],"properties":{"service_id":{"type":"integer","format":"int64","description":"ID of the service/game to launch (required)","example":10},"amount":{"type":"string","nullable":true,"description":"Amount to transfer to provider (optional, defaults to full wallet balance for transfer providers)","example":"100.00"}}},"LaunchServiceResponse":{"type":"object","properties":{"login_url":{"type":"string","description":"Game login redirect URL","example":"https://game.jili.com/launch/abc123"}}},"RestoreBalanceRequest":{"type":"object","properties":{"provider_id":{"type":"integer","format":"int64","description":"Provider ID (optional, restore from specific provider)","example":1}}},"RestoreBalanceResponse":{"type":"object","properties":{"message":{"type":"string","description":"Restore operation result message","example":"Balance restored successfully"},"balance":{"type":"string","description":"Current user balance after restore","example":"120.50"}}},"BetHistoryResponse":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of matching records","example":20},"records":{"type":"array","description":"List of bet history records","items":{"$ref":"#/components/schemas/BetHistoryRecord"}}}},"BetHistoryRecord":{"type":"object","properties":{"theone_id":{"type":"string","description":"Provider's internal record ID","example":"831399640"},"bet_id":{"type":"string","description":"Unique bet identifier","example":"8553_1_831399640000"},"game_code":{"type":"string","description":"Game code","example":"vs20olympgate"},"game_name":{"type":"string","description":"Game display name","example":"Gates of Olympus"},"provider_category_name":{"type":"string","description":"Provider category name","example":"Pragmatic Play"},"product":{"type":"string","description":"Product type","example":"SL"},"bet_amount":{"type":"string","description":"Bet amount (decimal as string)","example":"40.0000"},"payout_amount":{"type":"string","description":"Payout amount (decimal as string)","example":"25.2400"},"win_loss":{"type":"string","description":"Win/loss amount (decimal as string)","example":"-14.7600"},"bet_time":{"type":"string","format":"date-time","description":"Bet placement time (ISO 8601 with +08:00)","example":"2026-03-03T14:38:28+08:00"},"settle_time":{"type":"string","format":"date-time","description":"Bet settlement time (ISO 8601 with +08:00)","example":"2026-03-03T14:40:51+08:00"},"status":{"type":"string","description":"Bet status: Y=Settled, N=Voided, P=Pending","example":"Y"}}},"AdminBetHistoryResponse":{"type":"object","properties":{"betHistories":{"type":"array","description":"List of admin bet history records","items":{"$ref":"#/components/schemas/AdminBetHistoryRecord"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"AdminBetHistoryRecord":{"type":"object","properties":{"user_id":{"type":"string","description":"User ID","example":"usr_abc123"},"provider_id":{"type":"integer","format":"int64","description":"Provider ID","example":500001},"bet_id":{"type":"string","description":"Unique bet identifier","example":"8553_1_835905201000"},"game_code":{"type":"string","description":"Game code","example":"vs20olympgold"},"game_name":{"type":"string","description":"Multi-language game name as JSON string","example":"{\"en\":\"Gates of Olympus Super Scatter\",\"zh\":\"奧林帕斯之門\"}"},"player":{"type":"string","description":"Provider member token","example":"MBR_TOKEN_ABC"},"round_id":{"type":"string","description":"Round identifier","example":"835905201"},"meta_options":{"type":"string","description":"Provider-specific metadata as JSON string","example":"{\"product\":\"SL\"}"},"bet_amount":{"type":"string","description":"Bet amount (decimal as string)","example":"10.0000"},"payout_amount":{"type":"string","description":"Payout amount (decimal as string)","example":"15.5000"},"win_loss":{"type":"string","description":"Win/loss amount (decimal as string)","example":"5.5000"},"valid_turnover":{"type":"string","description":"Valid turnover (decimal as string)","example":"10.0000"},"bet_time":{"type":"string","format":"date-time","description":"Bet placement time (ISO 8601 with +08:00)","example":"2026-03-18T16:18:40+08:00"},"settle_time":{"type":"string","format":"date-time","description":"Bet settlement time (ISO 8601 with +08:00)","example":"2026-03-18T16:18:50+08:00"},"status":{"type":"string","description":"Bet status: Y=Settled, N=Voided, P=Pending","example":"Y"},"is_finished":{"type":"boolean","description":"Whether the bet has been settled","example":true}}},"PromotionItem":{"type":"object","properties":{"id":{"type":"integer","format":"int64","description":"Promotion ID","example":1},"title":{"type":"string","description":"Promotion title","example":"Welcome Bonus 100%"},"description":{"type":"string","description":"Promotion description","example":"Get 100% bonus on your first deposit"},"terms_conditions":{"type":"string","description":"Terms and conditions text","example":"Minimum deposit 100. Max bonus 5000."},"bonus_type":{"type":"integer","description":"Bonus type (1=percentage, 2=fixed amount, 3=random)","enum":[1,2,3],"example":1},"bonus_value":{"type":"number","format":"double","description":"Bonus value. If bonus_type=1 and value=50, means 50%","example":100},"max_payout":{"type":"number","format":"double","description":"Maximum bonus payout cap (caps the bonus amount at claim time)","example":5000},"max_withdrawal":{"type":"number","format":"double","description":"Maximum amount withdrawable to real_bal after hitting turnover requirement","example":50},"claim_condition_type":{"type":"integer","description":"Claim condition type (1=deposit, 2=free, 3=custom)","enum":[1,2,3],"example":1},"claim_conditions":{"type":"string","description":"JSON string with typed schema per claim_condition_type:\n- type 1 (deposit): {\"min_deposit\": 100}\n- type 2 (free): {} (no conditions)\n- type 3 (custom): {\"min_deposit_amount\": 100, \"min_deposit_count\": 1, \"payment_methods\": [\"gcash\"]}\n","example":"{\"min_deposit\": 100}"},"start_date":{"type":"string","format":"date-time","description":"Start date (ISO 8601 with +08:00, empty string = no start date)","example":""},"end_date":{"type":"string","format":"date-time","description":"End date (ISO 8601 with +08:00, empty string = no end date)","example":"2026-04-01T00:00:00+08:00"},"turnover":{"type":"number","format":"double","description":"Wagering/turnover multiplier requirement","example":20},"winover":{"type":"number","format":"double","description":"Winover requirement","example":0},"provider_category_ids":{"type":"string","description":"JSON array of provider_categories.id","example":"[1, 3, 5]"},"banner_image_url":{"type":"string","description":"Banner image URL","example":"https://cdn.example.com/banner.png"},"promo_image_url":{"type":"string","description":"Promotion image URL","example":"https://cdn.example.com/promo.png"},"status":{"type":"integer","description":"Status (0=inactive, 1=active)","enum":[0,1],"example":1},"sort_order":{"type":"integer","description":"Display sort order (lower = first)","example":0},"promotion_category_id":{"type":"integer","format":"int64","description":"Promotion category ID (required, default 1 = Welcome Bonus)","example":1},"min_topup_amount":{"type":"number","format":"double","description":"Minimum top-up amount required to claim","example":0},"max_topup_amount":{"type":"number","format":"double","description":"Maximum top-up amount allowed for claim","example":0},"min_times_of_topup":{"type":"integer","description":"Minimum number of top-ups required to claim","example":0},"claim_limit":{"type":"integer","description":"Maximum number of times a player can claim this promotion (0 = one-time only)","example":0},"claim_reset":{"type":"integer","description":"Claim counter reset period (0=none, 1=daily, 2=weekly)","enum":[0,1,2],"example":0},"initial_free_limit":{"type":"integer","description":"Number of free claims allowed for new players","example":0},"deposit_free_limit":{"type":"integer","description":"Number of free claims allowed after deposit","example":0},"display_type":{"type":"integer","description":"Display type (1=icon, 2=banner)","enum":[1,2],"example":1},"display_description_only":{"type":"boolean","description":"Whether to show only description text (derived from claim_conditions JSON)","example":false},"display_angpao_text":{"type":"boolean","description":"Whether to display angpao/red-packet text (derived from claim_conditions JSON)","example":false},"promotion_category_name":{"type":"string","description":"Name of the promotion category (joined field)","example":"Welcome Bonus"},"turnover_winover_type":{"type":"integer","description":"How turnover/winover value is interpreted (1=multiplier, 2=fixed amount)","enum":[1,2],"example":1},"created_by":{"type":"string","description":"ID of the admin who created the promotion","example":"admin-user-id"},"created_at":{"type":"string","format":"date-time","description":"Created datetime (ISO 8601 with +08:00)","example":"2026-02-26T00:00:00+08:00"},"updated_at":{"type":"string","format":"date-time","description":"Updated datetime (ISO 8601 with +08:00)","example":"2026-02-26T00:00:00+08:00"},"is_clearable":{"type":"boolean","description":"Whether bonus_bal can be cleared in any amount (true) or only when bonus_bal <= 0.1 (false)","example":false},"is_claimable":{"type":"boolean","description":"Per-promotion claimability for display (dim/light tile, show/hide claim button).\nfalse when user fails any of:\n- Claim limit exceeded (daily/weekly/once)\n- Outside allowed claim time (claim_time config)\n- User is in excluded_users list or not in included_users list\n- Deposit condition not met (min_deposit, min_topup, etc.)\nDefaults to true for unauthenticated users.\n","example":true}}},"CreatePromotionRequest":{"type":"object","required":["title","description","bonus_type","promotion_category_id"],"properties":{"title":{"type":"string","description":"Promotion title (required)","example":"Welcome Bonus 100%"},"description":{"type":"string","description":"Promotion description (required)","example":"Get 100% bonus on your first deposit"},"terms_conditions":{"type":"string","description":"Terms and conditions text"},"bonus_type":{"type":"integer","description":"Bonus type (required). 1=percentage, 2=fixed amount","enum":[1,2],"example":1},"bonus_value":{"type":"number","format":"double","description":"Bonus value","example":100},"max_payout":{"type":"number","format":"double","description":"Maximum bonus payout cap (caps the bonus amount at claim time)","example":5000},"max_withdrawal":{"type":"number","format":"double","description":"Maximum amount withdrawable to real_bal after hitting turnover requirement","example":50},"claim_condition_type":{"type":"integer","description":"Claim condition type (1=deposit, 2=free, 3=custom). Defaults to 1 (deposit)","enum":[1,2,3],"default":1,"example":1},"claim_conditions":{"type":"string","description":"JSON string matching the claim_condition_type schema:\n- type 1 (deposit): {\"min_deposit\": 100}\n- type 2 (free): {} or empty\n- type 3 (custom): {\"min_deposit_amount\": 100, \"min_deposit_count\": 1, \"payment_methods\": [\"gcash\"]}\n","example":"{\"min_deposit\": 100}"},"start_date":{"type":"string","format":"date-time","description":"Start date (ISO 8601 with +08:00, e.g. 2026-02-26T00:00:00+08:00). Empty string = no start date","example":""},"end_date":{"type":"string","format":"date-time","description":"End date (ISO 8601 with +08:00, e.g. 2026-05-26T23:59:59+08:00). Empty string = no end date","example":"2026-04-01T00:00:00+08:00"},"turnover":{"type":"number","format":"double","description":"Wagering/turnover multiplier","example":20},"winover":{"type":"number","format":"double","description":"Winover requirement","example":0},"provider_category_ids":{"type":"string","description":"JSON array of provider_categories.id","example":"[1, 3, 5]"},"banner_image_url":{"type":"string","description":"Banner image URL"},"promo_image_url":{"type":"string","description":"Promotion image URL"},"status":{"type":"integer","description":"Status (0=inactive, 1=active)","enum":[0,1],"example":1},"sort_order":{"type":"integer","description":"Display sort order (lower = first)","example":0},"category_id":{"type":"integer","format":"int64","description":"Promotion category ID (required, must exist). Default 1 = Welcome Bonus","example":1},"display_type":{"type":"integer","description":"Display type (1=icon, 2=banner). Default 1","enum":[1,2],"example":1}}},"GetPromotionResponse":{"type":"object","properties":{"promotion":{"$ref":"#/components/schemas/PromotionItem"}}},"UpdatePromotionRequest":{"type":"object","description":"Only provided/non-empty fields are applied (partial update). Omit a field to leave it unchanged; explicitly send 0 to update numeric fields to 0.","properties":{"title":{"type":"string","description":"Promotion title","example":"Welcome Bonus 150%"},"description":{"type":"string","description":"Promotion description"},"terms_conditions":{"type":"string","description":"Terms and conditions text"},"bonus_type":{"type":"integer","description":"Bonus type (1=percentage, 2=fixed amount)","enum":[1,2]},"bonus_value":{"type":"number","format":"double","description":"Bonus value","example":150},"max_payout":{"type":"number","format":"double","description":"Maximum bonus payout cap (caps the bonus amount at claim time)","example":7500},"max_withdrawal":{"type":"number","format":"double","description":"Maximum amount withdrawable to real_bal after hitting turnover requirement","example":50},"claim_condition_type":{"type":"integer","description":"Claim condition type (1=deposit, 2=free, 3=custom)","enum":[1,2,3]},"claim_conditions":{"type":"string","description":"JSON string matching claim_condition_type schema"},"start_date":{"type":"string","format":"date-time","description":"Start date (ISO 8601 with +08:00)"},"end_date":{"type":"string","format":"date-time","description":"End date (ISO 8601 with +08:00)"},"turnover":{"type":"number","format":"double","description":"Wagering/turnover multiplier"},"winover":{"type":"number","format":"double","description":"Winover requirement"},"provider_category_ids":{"type":"string","description":"JSON array of provider_categories.id"},"banner_image_url":{"type":"string","description":"Banner image URL"},"promo_image_url":{"type":"string","description":"Promotion image URL"},"status":{"type":"integer","description":"Status (0=inactive, 1=active)","enum":[0,1],"example":1},"sort_order":{"type":"integer","description":"Display sort order (lower = first)"},"promotion_category_id":{"type":"integer","format":"int64","description":"Promotion category ID (must exist if provided)"},"display_type":{"type":"integer","description":"Display type (1=icon, 2=banner)","enum":[1,2]}}},"AdminPromotionsResponse":{"type":"object","properties":{"promotions":{"type":"array","description":"List of promotions","items":{"$ref":"#/components/schemas/PromotionItem"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"PromotionsResponse":{"type":"object","properties":{"promotions":{"type":"array","description":"List of active promotions","items":{"$ref":"#/components/schemas/PromotionItem"}}}},"PlayerPromotionRecordItem":{"type":"object","properties":{"id":{"type":"integer","format":"int64","description":"Record ID","example":1},"promotion_id":{"type":"integer","format":"int64","description":"Promotion ID","example":1},"promotion_title":{"type":"string","description":"Promotion title at time of claim","example":"Welcome Bonus 100%"},"user_id":{"type":"string","description":"Player user ID","example":"user-123"},"name":{"type":"string","description":"Player name","example":"user-123"},"target_turnover":{"type":"number","format":"double","description":"Required total turnover to complete (bonus_bal * turnover multiplier)","example":4000},"current_turnover":{"type":"number","format":"double","description":"Current accumulated turnover","example":1500.5},"bonus_amount":{"type":"number","format":"double","description":"Bonus amount granted","example":100},"max_withdrawal":{"type":"number","format":"double","description":"Maximum withdrawal allowed from bonus","example":5000},"status":{"type":"integer","description":"Record status (0=pending, 1=in_progress, 2=completed, 3=expired)","enum":[0,1,2,3],"example":1},"claimed_at":{"type":"string","format":"date-time","description":"Claimed datetime (ISO 8601 with +08:00, empty string if not yet claimed)","example":"2026-02-26T00:00:00+08:00"},"completed_at":{"type":"string","format":"date-time","description":"Completed datetime (ISO 8601 with +08:00, empty string if not completed)","example":""},"created_at":{"type":"string","format":"date-time","description":"Created datetime (ISO 8601 with +08:00)","example":"2026-02-26T00:00:00+08:00"},"updated_at":{"type":"string","format":"date-time","description":"Updated datetime (ISO 8601 with +08:00)","example":"2026-02-26T20:00:00+08:00"}}},"ListPlayerPromotionRecordsResponse":{"type":"object","properties":{"records":{"type":"array","description":"List of player promotion records","items":{"$ref":"#/components/schemas/PlayerPromotionRecordItem"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"ExportPlayerPromotionRecordsResponse":{"type":"object","properties":{"csv_data":{"type":"string","format":"byte","description":"Base64-encoded CSV data. Headers:\nID, Promotion ID, Promotion Title, User ID, Name,\nTarget Turnover, Current Turnover, Bonus Amount, Max Withdrawal,\nStatus, Claimed At, Completed At, Created At, Updated At\n","example":"SUQsUHJvbW90aW9uIElELC4uLg=="}}},"ClaimPromotionResponse":{"type":"object","properties":{"record_id":{"type":"integer","format":"int64","description":"Created PlayerPromotionRecord ID","example":42},"bonus_amount":{"type":"number","format":"double","description":"Bonus amount granted","example":100},"message":{"type":"string","description":"Success message with bonus and target turnover details","example":"Promotion claimed successfully. Bonus: 100.00, Target turnover: 4000.00"}}},"PromotionCategoryItem":{"type":"object","properties":{"id":{"type":"integer","format":"int64","description":"Promotion category ID","example":1},"name":{"type":"string","description":"Category name","example":"Welcome Bonus"},"description":{"type":"string","description":"Category description","example":"Welcome bonus promotions for new players"},"sort_order":{"type":"integer","description":"Display sort order (lower = first)","example":0},"banner_url":{"type":"string","description":"Category banner image URL","example":"https://cdn.example.com/category-banner.png"},"status":{"type":"integer","description":"Status (0=inactive, 1=active)","enum":[0,1],"example":1},"created_at":{"type":"string","format":"date-time","description":"Created datetime (ISO 8601 with +08:00)","example":"2026-02-26T00:00:00+08:00"},"updated_at":{"type":"string","format":"date-time","description":"Updated datetime (ISO 8601 with +08:00)","example":"2026-02-26T00:00:00+08:00"}}},"CreatePromotionCategoryRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Category name (required)","example":"Welcome Bonus"},"description":{"type":"string","description":"Category description","example":"Welcome bonus promotions for new players"},"sort_order":{"type":"integer","description":"Display sort order (lower = first)","example":0},"banner_url":{"type":"string","description":"Category banner image URL"},"status":{"type":"integer","description":"Status (0=inactive, 1=active)","enum":[0,1],"example":1}}},"GetPromotionCategoryResponse":{"type":"object","properties":{"category":{"$ref":"#/components/schemas/PromotionCategoryItem"}}},"UpdatePromotionCategoryRequest":{"type":"object","description":"Only provided/non-empty fields are applied (partial update). Omit a field to leave it unchanged; explicitly send 0 to update numeric fields to 0.","properties":{"name":{"type":"string","description":"Category name","example":"Hot Promotion"},"description":{"type":"string","description":"Category description"},"sort_order":{"type":"integer","description":"Display sort order (lower = first)"},"banner_url":{"type":"string","description":"Category banner image URL"},"status":{"type":"integer","description":"Status (0=inactive, 1=active)","enum":[0,1]}}},"AdminPromotionCategoriesResponse":{"type":"object","properties":{"categories":{"type":"array","description":"List of promotion categories","items":{"$ref":"#/components/schemas/PromotionCategoryItem"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"PromotionCategoriesResponse":{"type":"object","properties":{"categories":{"type":"array","description":"List of active promotion categories","items":{"$ref":"#/components/schemas/PromotionCategoryItem"}}}},"GetProviderCredentialListResponse":{"type":"object","properties":{"items":{"type":"array","description":"List of providers with credential info","items":{"$ref":"#/components/schemas/ProviderCredentialItem"}}}},"ProviderCredentialItem":{"type":"object","properties":{"provider_id":{"type":"integer","format":"int64","description":"Provider ID","example":1},"provider_code":{"type":"string","description":"Provider code","example":"JILI"},"provider_name":{"type":"string","description":"Provider display name","example":"JILI"},"credential_fields":{"type":"array","description":"Credential schema fields defining what values are needed","items":{"$ref":"#/components/schemas/CredentialSchemaField"}},"provider_categories":{"type":"array","description":"Provider categories with their current status","items":{"$ref":"#/components/schemas/ProviderCategoryStatusItem"}},"has_credentials":{"type":"boolean","description":"Whether credentials are already configured for this tenant+provider","example":false},"status":{"type":"boolean","description":"Current credential status (false if not configured)","example":false}}},"CredentialSchemaField":{"type":"object","properties":{"key":{"type":"string","description":"Field key (used as JSON key in credentials object)","example":"agent_id"},"label":{"type":"string","description":"Human-readable field label","example":"Agent ID"},"type":{"type":"string","description":"Field type: text, secret, url, number","example":"text"},"required":{"type":"boolean","description":"Whether this field is required","example":true}}},"ProviderCategoryStatusItem":{"type":"object","properties":{"id":{"type":"integer","format":"int64","description":"Provider category ID","example":1},"name":{"type":"string","description":"Provider category name","example":"JILI - SLOTS"},"status":{"type":"boolean","description":"Whether this category is enabled","example":true}}},"SaveProviderCredentialRequest":{"type":"object","required":["provider_id","credential_fields","api_url"],"properties":{"provider_id":{"type":"integer","format":"int64","description":"Provider ID (required)","example":1},"api_url":{"type":"string","description":"Provider API base URL (required)","example":"https://api.jili.com/v1"},"credential_fields":{"type":"string","description":"JSON string of credential key-value pairs (required, must be valid JSON matching provider's credential schema)","example":"{\"agent_id\":\"AG123\",\"agent_key\":\"secret-key-here\"}"},"status":{"type":"boolean","description":"Enable or disable the provider (optional, defaults to false)","default":false,"example":true},"env":{"type":"string","description":"Environment (optional, defaults to 'staging')","default":"staging","example":"staging"},"kiosk_url":{"type":"string","description":"Kiosk URL (optional, defaults to empty)","example":""},"kiosk_username":{"type":"string","description":"Kiosk username (optional, defaults to empty)","example":""},"kiosk_password":{"type":"string","description":"Kiosk password (optional, will be encrypted if provided)","example":""},"remark":{"type":"string","description":"Admin remark/note (optional, defaults to empty)","example":""},"provider_categories":{"type":"array","description":"Optional batch update of provider category statuses","items":{"$ref":"#/components/schemas/CategoryStatusUpdate"}}}},"CategoryStatusUpdate":{"type":"object","required":["category_id","status"],"properties":{"category_id":{"type":"integer","format":"int64","description":"Provider category ID","example":1},"status":{"type":"boolean","description":"Enable (true) or disable (false)","example":true}}},"SaveProviderCredentialResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the save was successful","example":true},"is_valid":{"type":"boolean","description":"Whether the auto connection test passed","example":true},"message":{"type":"string","description":"Result message (includes connection test outcome)","example":"Credentials saved and connection verified"}}},"GetProviderCredentialStatusResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ProviderCredentialStatusItem"}}}},"ProviderCredentialStatusItem":{"type":"object","properties":{"provider_id":{"type":"integer","format":"int64","description":"Provider ID","example":1},"provider_code":{"type":"string","description":"Provider code","example":"JILI"},"provider_name":{"type":"string","description":"Provider display name","example":"JILI"},"configured":{"type":"boolean","description":"Whether credentials exist for this tenant+provider","example":true},"api_url":{"type":"string","description":"Provider API base URL","example":"https://api.jili.com/v1"},"status":{"type":"boolean","description":"Provider enabled/disabled status","example":true},"is_valid":{"type":"boolean","description":"Whether last connection test passed","example":true},"is_whitelist":{"type":"boolean","description":"Whether provider requires IP whitelist (from providers table)","example":false},"need_topup":{"type":"boolean","description":"Whether provider requires balance top-up (from providers table)","example":false},"env":{"type":"string","description":"Environment","example":"staging"},"kiosk_url":{"type":"string","description":"Kiosk URL","example":""},"kiosk_username":{"type":"string","description":"Kiosk username","example":""},"has_kiosk_password":{"type":"boolean","description":"Whether a kiosk password is configured (value not returned)","example":false},"remark":{"type":"string","description":"Admin remark","example":""},"updated_at":{"type":"string","format":"date-time","description":"Last updated datetime (ISO 8601 with +08:00)","example":"2026-03-16T12:00:00+08:00"},"verified_at":{"type":"string","format":"date-time","description":"Last successful connection test datetime (ISO 8601 with +08:00, empty if never verified)","example":"2026-03-16T12:00:00+08:00"},"field_keys":{"type":"array","description":"List of configured credential field keys (values not returned)","items":{"type":"string"},"example":["agent_id","agent_key"]}}},"TestProviderConnectionResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the connection test passed","example":true},"message":{"type":"string","description":"Test result message","example":"Connected successfully"},"latency_ms":{"type":"integer","format":"int64","description":"Connection test latency in milliseconds","example":142}}},"GetProviderCredentialValuesResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ProviderCredentialValuesItem"}}}},"ProviderCredentialValuesItem":{"type":"object","properties":{"provider_id":{"type":"integer","format":"int64","description":"Provider ID","example":1},"provider_code":{"type":"string","description":"Provider code","example":"JILI"},"provider_name":{"type":"string","description":"Provider display name","example":"JILI"},"api_url":{"type":"string","description":"Provider API base URL","example":"https://api.jili.com/v1"},"credential_fields":{"type":"object","additionalProperties":{"type":"string"},"description":"Decrypted credential values (secret fields are masked, e.g. ******22f0)","example":{"agent_id":"AG123","agent_key":"******here"}},"status":{"type":"boolean","description":"Provider enabled/disabled status","example":true},"is_valid":{"type":"boolean","description":"Whether last connection test passed","example":true},"is_whitelist":{"type":"boolean","description":"Whether provider requires IP whitelist (from providers table)","example":false},"need_topup":{"type":"boolean","description":"Whether provider requires balance top-up (from providers table)","example":false},"env":{"type":"string","description":"Environment","example":"staging"},"kiosk_url":{"type":"string","description":"Kiosk URL","example":""},"kiosk_username":{"type":"string","description":"Kiosk username","example":""},"kiosk_password":{"type":"string","description":"Kiosk password (masked, e.g. ******xxxx)","example":""},"remark":{"type":"string","description":"Admin remark","example":""},"verified_at":{"type":"string","format":"date-time","description":"Last successful connection test datetime (ISO 8601 with +08:00)","example":"2026-03-16T12:00:00+08:00"}}},"UpdateCategoryStatusResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the update was successful","example":true},"message":{"type":"string","description":"Result message","example":"Category enabled"}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number","example":1},"page_size":{"type":"integer","description":"Items per page","example":20},"total":{"type":"integer","format":"int64","description":"Total number of records","example":50},"total_pages":{"type":"integer","description":"Total number of pages","example":3}}}}}}