Zeus API ======== The Zeus API provides web-specific endpoints for the Zocial platform, including configuration, campaigns, tasks, and user management. Configuration ------------- Get Config ~~~~~~~~~~ Retrieve platform configuration and settings. .. http:post:: /web/api/get/config/ **Response:** .. code-block:: json { "platform": { "name": "Zocial", "version": "3.0.0", "environment": "production" }, "features": { "social_networks": ["instagram", "facebook", "twitter", "youtube"], "payment_methods": ["bank_transfer", "paypal", "stripe"], "languages": ["en", "es", "pl"], "currencies": ["USD", "EUR", "PLN"] }, "limits": { "max_campaigns_per_user": 10, "max_networks_per_user": 5, "min_payout_amount": 50, "max_payout_amount": 10000 }, "settings": { "maintenance_mode": false, "registration_enabled": true, "social_login_enabled": true } } Campaign Management ------------------ Get Campaigns ~~~~~~~~~~~~~ Retrieve campaigns for web interface. .. http:post:: /web/api/get/campaigns/ **Request Body:** .. code-block:: text filter=active category=fashion page=1 limit=20 **Response:** .. code-block:: json { "campaigns": [ { "id": 123, "type": "influencer", "name": "Summer Fashion Campaign", "tagline": "Show off your summer style", "description": "Promote our latest summer collection", "image_logo": "https://example.com/logo.jpg", "image_post": "https://example.com/post.jpg", "hashtags": ["#summer", "#fashion"], "date_end": { "year": 2024, "month": 8, "day": 31, "hour": 23, "minute": 59, "second": 59 }, "networks": ["instagram", "facebook"], "currency": "USD", "tasks": { "time": 72, "time_type": "hours", "bonus": { "active": true, "promo_reach": 50, "promo_engagement_rate": 25, "promo_best_post": 100 }, "minimum_reward": 25 }, "tasks_featured": true, "tasks_leaderboard": true, "status": "active", "participants_count": 50, "completion_rate": 85 } ], "total": 100, "page": 1, "limit": 20 } Get Campaign ~~~~~~~~~~~~ Retrieve detailed campaign information. .. http:post:: /web/api/get/campaign/ **Request Body:** .. code-block:: text id=123 **Response:** .. code-block:: json { "id": 123, "type": "influencer", "name": "Summer Fashion Campaign", "tagline": "Show off your summer style", "description": "Promote our latest summer collection", "image_logo": "https://example.com/logo.jpg", "image_post": "https://example.com/post.jpg", "hashtags": ["#summer", "#fashion"], "date_end": { "year": 2024, "month": 8, "day": 31, "hour": 23, "minute": 59, "second": 59 }, "networks": ["instagram", "facebook"], "currency": "USD", "tasks": { "time": 72, "time_type": "hours", "bonus": { "active": true, "promo_reach": 50, "promo_engagement_rate": 25, "promo_best_post": 100 }, "minimum_reward": 25 }, "tasks_featured": true, "tasks_leaderboard": true, "publisher": { "social_users_available": { "instagram": true, "facebook": false }, "social_pages_available": { "instagram": true, "facebook": true }, "social_walls_available": { "instagram": false, "facebook": true }, "social_channels_available": { "instagram": false, "facebook": false } }, "attachment": "https://example.com/attachment.pdf", "participants": [ { "user_id": 456, "username": "influencer1", "avatar": "https://example.com/avatar1.jpg", "joined_at": "2024-08-01T10:00:00Z", "completed_tasks": 3, "total_earned": 75 } ], "statistics": { "total_participants": 50, "active_participants": 35, "completed_tasks": 150, "total_reach": 50000, "total_engagement": 2500 } } Campaign Actions ~~~~~~~~~~~~~~~ Join Campaign ^^^^^^^^^^^^ Join a campaign as an influencer. .. http:post:: /web/api/campaign/join/ **Request Body:** .. code-block:: text campaign_id=123 **Response:** .. code-block:: json { "status": "success", "message": "Successfully joined campaign", "campaign_id": 123 } Task Management --------------- Get Tasks ~~~~~~~~~ Retrieve tasks for a campaign. .. http:post:: /web/api/get/tasks/ **Request Body:** .. code-block:: text campaign_id=123 **Response:** .. code-block:: json { "tasks": [ { "id": 456, "type": "post", "title": "Create Instagram Post", "description": "Post about our summer collection", "requirements": "Include hashtags and tag our brand", "deadline": "2024-08-31T23:59:59Z", "status": "pending", "bonus": { "reach": 50, "engagement_rate": 25, "best_post": 100 }, "payments": { "minimum": 25, "post": 30, "total": 30 }, "info": { "title": "Task Requirements", "content": "Detailed task requirements..." }, "campaign": { "id": 123, "name": "Summer Fashion Campaign", "type": "influencer", "tagline": "Show off your summer style", "description": "Promote our latest summer collection", "image_logo": "https://example.com/logo.jpg", "image_post": "https://example.com/post.jpg", "hashtags": ["#summer", "#fashion"], "date_end": { "year": 2024, "month": 8, "day": 31, "hour": 23, "minute": 59, "second": 59 }, "date_end_text": "August 31, 2024 - 23:59:59", "networks": ["instagram", "facebook"], "currency": "USD" } } ] } Task Actions ~~~~~~~~~~~~ Complete Task ^^^^^^^^^^^^ Mark a task as completed. .. http:post:: /web/api/task/complete/ **Request Body:** .. code-block:: text task_id=456 post_url=https://instagram.com/p/example screenshots=https://example.com/screenshot1.jpg reach=1000 engagement=50 **Response:** .. code-block:: json { "status": "success", "message": "Task completed successfully", "payment": 30, "bonus_payment": 5, "total_payment": 35 } Leave Task ^^^^^^^^^^ Leave a task (cancel participation). .. http:post:: /web/api/task/leave/ **Request Body:** .. code-block:: text task_id=456 **Response:** .. code-block:: json { "status": "success", "message": "Task left successfully" } Leaderboard ----------- Get Leaderboard ~~~~~~~~~~~~~~~ Retrieve campaign leaderboard. .. http:post:: /web/api/get/leaderboard/ **Request Body:** .. code-block:: text campaign_id=123 **Response:** .. code-block:: json { "leaderboard": [ { "rank": 1, "user_id": 456, "username": "influencer1", "avatar": "https://example.com/avatar1.jpg", "score": 1500, "completed_tasks": 15, "total_earned": 450, "total_reach": 25000, "total_engagement": 1250 }, { "rank": 2, "user_id": 457, "username": "influencer2", "avatar": "https://example.com/avatar2.jpg", "score": 1200, "completed_tasks": 12, "total_earned": 360, "total_reach": 20000, "total_engagement": 1000 } ], "user_rank": 5, "user_score": 800 } User Management --------------- Get Profile ~~~~~~~~~~~ Retrieve user profile information. .. http:post:: /web/api/get/profile/ **Response:** .. code-block:: json { "user_id": 456, "username": "influencer1", "email": "user@example.com", "first_name": "John", "last_name": "Doe", "avatar": "https://example.com/avatar.jpg", "country": { "id": 1, "name": "United States" }, "city": { "id": 1, "name": "New York" }, "language": "en", "joined_date": "2024-01-01T00:00:00Z", "last_login": "2024-08-01T10:00:00Z", "statistics": { "total_campaigns": 10, "completed_tasks": 50, "total_earned": 1500, "total_reach": 100000, "total_engagement": 5000 } } Update Profile ^^^^^^^^^^^^^ Update user profile information. .. http:post:: /web/api/update/profile/ **Request Body:** .. code-block:: json { "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+1234567890", "country": 1, "city": 1, "bio": "Fashion and lifestyle influencer" } **Response:** .. code-block:: json { "status": "success", "message": "Profile updated successfully" } Update Preferences ^^^^^^^^^^^^^^^^^ Update user preferences. .. http:post:: /web/api/update/preferences/ **Request Body:** .. code-block:: json { "categories": ["fashion", "beauty"], "networks": ["instagram", "facebook"], "language": "en", "notifications": { "new_campaign": true, "end_campaign": true, "near_campaign": true } } **Response:** .. code-block:: json { "status": "success", "message": "Preferences updated successfully" } Update Notifications ^^^^^^^^^^^^^^^^^^^^ Update notification settings. .. http:post:: /web/api/update/notifications/ **Request Body:** .. code-block:: json { "new_campaign": true, "end_campaign": false, "near_campaign": true, "cause_campaign": true, "profile_status": true, "post_status": true, "update_balance": true } **Response:** .. code-block:: json { "status": "success", "message": "Notification settings updated" } Update Language ^^^^^^^^^^^^^^ Update user language preference. .. http:post:: /web/api/update/language/ **Request Body:** .. code-block:: json { "language": "es" } **Response:** .. code-block:: json { "status": "success", "message": "Language updated successfully" } Social Networks -------------- Get Networks ~~~~~~~~~~~~ Retrieve user's connected social networks. .. http:post:: /web/api/get/networks/ **Response:** .. code-block:: json { "networks": [ { "id": 123, "network": "instagram", "network_id": "user123", "network_url": "https://instagram.com/user123", "status": "accepted", "followers": 5000, "verified": true, "connected_at": "2024-01-01T00:00:00Z" }, { "id": 124, "network": "facebook", "network_id": "page456", "network_url": "https://facebook.com/page456", "status": "pending", "followers": 2000, "verified": false, "connected_at": "2024-01-15T00:00:00Z" } ] } Network Actions ~~~~~~~~~~~~~~~ Network Approval ^^^^^^^^^^^^^^^ Submit network for approval. .. http:post:: /web/api/network/approval/ **Request Body:** .. code-block:: json { "network_type": "instagram", "network_id": "user123", "network_url": "https://instagram.com/user123", "followers": 5000, "category": "fashion" } **Response:** .. code-block:: json { "status": "success", "message": "Network submitted for approval", "approval_id": 789 } Update Network Extra ^^^^^^^^^^^^^^^^^^^ Update additional network information. .. http:post:: /web/api/network-extra/update/ **Request Body:** .. code-block:: json { "network_id": 123, "extra_data": { "bio": "Updated bio information", "website": "https://example.com", "category": "fashion", "engagement_rate": 3.5 } } **Response:** .. code-block:: json { "status": "success", "message": "Network extra information updated successfully" } Financial Management ------------------- Get Wallet ~~~~~~~~~~ Retrieve user's wallet information. .. http:post:: /web/api/get/wallet/ **Response:** .. code-block:: json { "user_id": 456, "available_balance": 750, "pending_balance": 250, "total_earned": 5000, "total_paid": 4000, "currency": "USD", "minimum_payout": 50, "payment_methods": [ { "id": "bank_transfer", "name": "Bank Transfer", "enabled": true }, { "id": "paypal", "name": "PayPal", "enabled": true } ] } Get Payouts ~~~~~~~~~~~ Retrieve user's payout history. .. http:post:: /web/api/get/payouts/ **Request Body:** .. code-block:: json { "page": 1, "limit": 20 } **Response:** .. code-block:: json { "payouts": [ { "id": 123, "amount": 500, "currency": "USD", "status": "completed", "method": "bank_transfer", "requested_at": "2024-08-01T10:00:00Z", "processed_at": "2024-08-02T15:30:00Z", "reference": "PAY-2024-001" } ], "total": 50, "page": 1, "limit": 20 } Update Bank Account ^^^^^^^^^^^^^^^^^^ Update user's bank account information. .. http:post:: /web/api/update/bank-account/ **Request Body:** .. code-block:: json { "bank_name": "Wells Fargo", "account_number": "1234567890", "routing_number": "021000021", "account_type": "checking", "account_holder_name": "John Doe" } **Response:** .. code-block:: json { "status": "success", "message": "Bank account updated successfully", "bank_account_id": 457 } Payout Request ^^^^^^^^^^^^^ Request a new payout. .. http:post:: /web/api/payout/request/ **Request Body:** .. code-block:: json { "amount": 500, "method": "bank_transfer", "bank_account_id": 456 } **Response:** .. code-block:: json { "status": "success", "message": "Payout request submitted successfully", "payout_id": 125, "reference": "PAY-2024-003", "estimated_processing_time": "2-3 business days" } Notifications ------------- Get Notifications ~~~~~~~~~~~~~~~~~ Retrieve user notifications. .. http:post:: /web/api/get/notifications/ **Request Body:** .. code-block:: json { "page": 1, "limit": 20 } **Response:** .. code-block:: json { "notifications": [ { "id": 456, "title": "New Campaign Available", "message": "A new fashion campaign is available", "type": "campaign", "read": false, "created_at": "2024-08-01T10:00:00Z", "data": { "campaign_id": 789, "campaign_name": "Summer Fashion Campaign" } } ], "total": 50, "page": 1, "limit": 20, "unread_count": 5 } Authentication ------------- Auth Check ~~~~~~~~~~ Check authentication status. .. http:post:: /web/api/auth/check/ **Response:** .. code-block:: json { "is_authenticated": true, "user_id": 456, "username": "user123" } Check Email ^^^^^^^^^^^ Check if email exists. .. http:post:: /web/api/auth/check/email/ **Request Body:** .. code-block:: json { "email": "user@example.com" } **Response:** .. code-block:: json { "exists": true, "available": false } Validate Social ^^^^^^^^^^^^^^^ Validate social authentication. .. http:post:: /web/api/auth/validate/social/ **Request Body:** .. code-block:: json { "provider": "facebook", "access_token": "facebook_access_token" } **Response:** .. code-block:: json { "valid": true, "user_data": { "id": "facebook_user_id", "name": "John Doe", "email": "john@example.com" } } Validate ^^^^^^^^ Validate user credentials. .. http:post:: /web/api/auth/validate/ **Request Body:** .. code-block:: json { "username": "user123", "password": "password123" } **Response:** .. code-block:: json { "valid": true, "user_id": 456 } Login ^^^^^ User login. .. http:post:: /web/api/auth/login/ **Request Body:** .. code-block:: json { "username": "user123", "password": "password123" } **Response:** .. code-block:: json { "status": "success", "message": "Login successful", "token": "jwt_token_here", "user": { "id": 456, "username": "user123", "email": "user@example.com" } } Register ^^^^^^^^ User registration. .. http:post:: /web/api/auth/register/ **Request Body:** .. code-block:: json { "username": "newuser", "email": "newuser@example.com", "password": "securepassword", "first_name": "John", "last_name": "Doe", "country": 1, "city": 1 } **Response:** .. code-block:: json { "status": "success", "message": "Account created successfully", "user_id": 789, "token": "jwt_token_here" } Logout ^^^^^^ User logout. .. http:post:: /web/api/auth/logout/ **Response:** .. code-block:: json { "status": "success", "message": "Logged out successfully" } Error Responses -------------- Authentication Errors ~~~~~~~~~~~~~~~~~~~~ .. code-block:: json { "error": "authentication_required", "message": "Authentication is required for this endpoint" } .. code-block:: json { "error": "invalid_credentials", "message": "Invalid username or password" } Validation Errors ~~~~~~~~~~~~~~~~ .. code-block:: json { "error": "validation_error", "message": "Invalid email format", "field": "email" } .. code-block:: json { "error": "validation_error", "message": "Username already exists", "field": "username" } Business Logic Errors ~~~~~~~~~~~~~~~~~~~~ .. code-block:: json { "error": "campaign_not_found", "message": "Campaign not found" } .. code-block:: json { "error": "campaign_full", "message": "Campaign is full" } .. code-block:: json { "error": "task_already_completed", "message": "Task has already been completed" } .. code-block:: json { "error": "insufficient_balance", "message": "Insufficient balance for payout request" }