{
    "success": true,
    "message": "Win with Wellness v2 API",
    "version": "2.0",
    "endpoints": {
        "verify_mobile": {
            "method": "POST",
            "url": "\/?endpoint=verify_mobile",
            "description": "Send OTP to mobile number for verification. Works for both new and existing customers.",
            "required": [
                "mobile_number"
            ],
            "optional": [
                "country_code",
                "preferred_contact"
            ],
            "notes": "Always sends OTP. Response indicates if customer is new (needs PIN setup) or existing (can use PIN for future logins)."
        },
        "pin_login": {
            "method": "POST",
            "url": "\/?endpoint=pin_login",
            "description": "Login using 4-digit PIN for existing customers",
            "required": [
                "mobile_number",
                "pin_code"
            ],
            "optional": [
                "country_code"
            ],
            "notes": "Fast login for existing customers who have set up their PIN"
        },
        "verify_otp": {
            "method": "POST",
            "url": "\/?endpoint=verify_otp",
            "description": "Verify OTP code",
            "required": [
                "mobile_number",
                "otp_code"
            ],
            "optional": [
                "country_code"
            ]
        },
        "resend_otp": {
            "method": "POST",
            "url": "\/?endpoint=resend_otp",
            "description": "Resend OTP for new customers (not yet registered)",
            "required": [
                "mobile_number"
            ],
            "optional": [
                "country_code",
                "preferred_contact"
            ],
            "notes": "Sends OTP via SMS or WhatsApp using Infobip\/Zoko. Only for new customers."
        },
        "set_pin": {
            "method": "POST",
            "url": "\/?endpoint=set_pin",
            "description": "Set 4-digit PIN after OTP verification",
            "required": [
                "mobile_number",
                "pin_code"
            ],
            "optional": [
                "country_code",
                "confirm_pin"
            ],
            "notes": "Requires recent OTP verification (within 30 minutes)"
        },
        "forgot_pin": {
            "method": "POST",
            "url": "\/?endpoint=forgot_pin",
            "description": "Send OTP for PIN reset (for customers who forgot their PIN)",
            "required": [
                "mobile_number"
            ],
            "optional": [
                "country_code",
                "preferred_contact",
                "istest"
            ],
            "notes": "Only works for customers who already have a PIN set. Sends OTP for PIN reset."
        },
        "reset_pin": {
            "method": "POST",
            "url": "\/?endpoint=reset_pin",
            "description": "Reset PIN after forgot PIN OTP verification",
            "required": [
                "mobile_number",
                "otp_code",
                "new_pin"
            ],
            "optional": [
                "country_code",
                "confirm_pin"
            ],
            "notes": "Requires valid OTP from forgot_pin endpoint. Sets new PIN for existing customers."
        },
        "get_customer": {
            "method": "GET",
            "url": "\/?endpoint=get_customer&mobile_number=XXXXX",
            "description": "Get customer information",
            "required": [
                "mobile_number"
            ],
            "optional": [
                "country_code"
            ]
        },
        "update_customer": {
            "method": "POST",
            "url": "\/?endpoint=update_customer",
            "description": "Update customer profile information",
            "required": [
                "mobile_number"
            ],
            "optional": [
                "name",
                "email",
                "preferred_contact",
                "country_code"
            ]
        },
        "get_transactions": {
            "method": "GET",
            "url": "\/?endpoint=get_transactions&mobile_number=XXXXX",
            "description": "Get customer transactions with optional POS sync using POSIntegration class",
            "required": [
                "mobile_number"
            ],
            "optional": [
                "limit",
                "offset",
                "sync_pos"
            ],
            "notes": "sync_pos parameter defaults to true. POS integration uses POSIntegration class with real-time sync to corniche02.dyndns.org:8121"
        },
        "add_transaction": {
            "method": "POST",
            "url": "\/?endpoint=add_transaction",
            "description": "Add new transaction",
            "required": [
                "mobile_number",
                "amount",
                "order_id"
            ],
            "optional": [
                "description"
            ]
        },
        "claim_points": {
            "method": "POST",
            "url": "\/?endpoint=claim_points",
            "description": "Claim points from POS system transactions",
            "required": [
                "mobile_number"
            ],
            "optional": [
                "country_code"
            ],
            "notes": "Syncs with POS system and adds new transactions. Called after OTP verification."
        },
        "validate_invoice": {
            "method": "POST",
            "url": "\/?endpoint=validate_invoice",
            "description": "Validate and add invoice manually for customers not in POS system",
            "required": [
                "mobile_number",
                "invoice_number"
            ],
            "optional": [
                "country_code"
            ],
            "notes": "Validates invoice through POS API and adds transaction manually"
        },
        "get_raffles": {
            "method": "GET",
            "url": "\/?endpoint=get_raffles",
            "description": "Get active raffles"
        },
        "pos_status": {
            "method": "GET",
            "url": "\/?endpoint=pos_status",
            "description": "Check POS system connectivity and status"
        },
        "test_pos": {
            "method": "GET",
            "url": "\/?endpoint=test_pos&mobile_number=XXXXX",
            "description": "Test POS API integration by searching with mobile number",
            "required": [
                "mobile_number"
            ],
            "notes": "Runs comprehensive tests: authentication, customer data, transaction history, data transformation"
        },
        "raffle_entries": {
            "method": "GET",
            "url": "\/?endpoint=raffle_entries&mobile_number=XXXXX",
            "description": "Get customer raffle entries with detailed breakdown",
            "required": [
                "mobile_number"
            ],
            "optional": [
                "country_code"
            ],
            "notes": "Shows individual raffle entries with entry types and descriptions"
        },
        "fix_raffle_entries": {
            "method": "GET",
            "url": "\/?endpoint=fix_raffle_entries",
            "description": "Fix existing raffle entries calculation (cumulative)",
            "notes": "One-time fix to correct existing data"
        },
        "admin_login": {
            "method": "POST",
            "url": "\/?endpoint=admin_login",
            "description": "Admin authentication",
            "required": [
                "username",
                "password"
            ],
            "notes": "Returns JWT token for admin access"
        },
        "admin_dashboard": {
            "method": "GET",
            "url": "\/?endpoint=admin_dashboard",
            "description": "Get dashboard overview statistics",
            "required": [
                "auth_token"
            ],
            "notes": "Returns key metrics, charts data, recent activities"
        },
        "admin_customers": {
            "method": "GET",
            "url": "\/?endpoint=admin_customers",
            "description": "Get customers list with pagination and filters",
            "required": [
                "auth_token"
            ],
            "optional": [
                "page",
                "limit",
                "search",
                "status",
                "sort"
            ],
            "notes": "Supports search by mobile\/name, status filter, sorting"
        },
        "admin_customer_details": {
            "method": "GET",
            "url": "\/?endpoint=admin_customer_details&customer_id=XXX",
            "description": "Get detailed customer information",
            "required": [
                "auth_token",
                "customer_id"
            ],
            "notes": "Returns customer info, transactions, points history, raffle entries"
        },
        "admin_transactions": {
            "method": "GET",
            "url": "\/?endpoint=admin_transactions",
            "description": "Get transactions list with filters",
            "required": [
                "auth_token"
            ],
            "optional": [
                "page",
                "limit",
                "customer_id",
                "date_from",
                "date_to",
                "source",
                "status",
                "branch_code"
            ],
            "notes": "Filter by customer, date range, source (pos\/manual), status, branch"
        },
        "admin_invoice_lookup": {
            "method": "GET",
            "url": "\/?endpoint=admin_invoice_lookup&invoice_number=XXX",
            "description": "Look up invoice details from POS system",
            "required": [
                "auth_token",
                "invoice_number"
            ],
            "notes": "Debug tool to inspect POS invoice data and verify amounts\/fields"
        },
        "admin_raffles": {
            "method": "GET",
            "url": "\/?endpoint=admin_raffles",
            "description": "Get raffle draws management",
            "required": [
                "auth_token"
            ],
            "notes": "List all raffle draws with statistics"
        },
        "admin_create_raffle": {
            "method": "POST",
            "url": "\/?endpoint=admin_create_raffle",
            "description": "Create new raffle draw",
            "required": [
                "auth_token",
                "draw_name",
                "start_date",
                "end_date"
            ],
            "optional": [
                "description",
                "prize_description"
            ],
            "notes": "Creates new raffle draw period"
        },
        "admin_raffle_entries": {
            "method": "GET",
            "url": "\/?endpoint=admin_raffle_entries&raffle_id=XXX",
            "description": "Get raffle entries for specific draw",
            "required": [
                "auth_token",
                "raffle_id"
            ],
            "optional": [
                "page",
                "limit"
            ],
            "notes": "List all entries for a raffle draw"
        },
        "admin_reports": {
            "method": "GET",
            "url": "\/?endpoint=admin_reports",
            "description": "Generate analytics reports",
            "required": [
                "auth_token",
                "report_type"
            ],
            "optional": [
                "date_from",
                "date_to",
                "format"
            ],
            "notes": "report_type: customers, transactions, raffles, points. format: json, csv"
        },
        "admin_settings": {
            "method": "GET",
            "url": "\/?endpoint=admin_settings",
            "description": "Get system settings",
            "required": [
                "auth_token"
            ],
            "notes": "Returns all configurable system settings"
        },
        "admin_update_settings": {
            "method": "POST",
            "url": "\/?endpoint=admin_update_settings",
            "description": "Update system settings",
            "required": [
                "auth_token",
                "settings"
            ],
            "notes": "Update multiple system settings at once"
        },
        "admin_manual_transaction": {
            "method": "POST",
            "url": "\/?endpoint=admin_manual_transaction",
            "description": "Create manual transaction for customer",
            "required": [
                "auth_token",
                "mobile_number",
                "amount",
                "description"
            ],
            "optional": [
                "points_override",
                "raffle_override"
            ],
            "notes": "Admin can manually add transactions and override calculations"
        },
        "admin_points_adjustment": {
            "method": "POST",
            "url": "\/?endpoint=admin_points_adjustment",
            "description": "Adjust customer points manually",
            "required": [
                "auth_token",
                "customer_id",
                "points_change",
                "reason"
            ],
            "notes": "For manual points corrections or bonuses"
        },
        "admin_upload_banner": {
            "method": "POST",
            "url": "\/?endpoint=admin_upload_banner",
            "description": "Upload banner image with title and link",
            "required": [
                "auth_token",
                "title",
                "image"
            ],
            "optional": [
                "description",
                "link",
                "order_index",
                "is_active"
            ],
            "notes": "Upload banner via multipart\/form-data or base64 JSON. Admin only."
        },
        "admin_manage_banners": {
            "method": "GET|PUT|DELETE",
            "url": "\/?endpoint=admin_manage_banners",
            "description": "List, update or delete banners",
            "required": [
                "auth_token"
            ],
            "optional": [
                "page",
                "limit",
                "id"
            ],
            "notes": "GET: list all, PUT: update banner, DELETE: remove banner. Admin only."
        },
        "get_banners": {
            "method": "GET",
            "url": "\/?endpoint=get_banners",
            "description": "Get active banners for frontend display",
            "required": [],
            "optional": [
                "limit",
                "format"
            ],
            "notes": "Public endpoint. format: base64|url. Returns active banners only."
        },
        "admin_export_data": {
            "method": "GET",
            "url": "\/?endpoint=admin_export_data",
            "description": "Export customer data in CSV or JSON format",
            "required": [
                "auth_token"
            ],
            "optional": [
                "format",
                "export_type",
                "date_from",
                "date_to",
                "customer_id"
            ],
            "notes": "format: json|csv, export_type: customers|transactions|raffles|full. Admin only."
        },
        "redeem_coupon": {
            "method": "POST",
            "url": "\/?endpoint=redeem_coupon",
            "description": "Redeem coupon code for free raffle entries",
            "required": [
                "mobile_number",
                "coupon_code"
            ],
            "optional": [
                "country_code"
            ],
            "notes": "Customers can enter coupon codes instead of invoices to get free raffle entries"
        },
        "admin_coupons": {
            "method": "GET|POST|PUT|DELETE",
            "url": "\/?endpoint=admin_coupons",
            "description": "Manage coupon codes - create, list, update, delete",
            "required": [
                "auth_token"
            ],
            "optional": [
                "page",
                "limit",
                "search",
                "status",
                "type",
                "id",
                "start_date",
                "end_date",
                "raffle_entries_reward"
            ],
            "notes": "GET: list coupons, POST: create (requires start_date, end_date), PUT: update (requires id), DELETE: deactivate (requires id). Admin only."
        },
        "admin_coupon_usage": {
            "method": "GET",
            "url": "\/?endpoint=admin_coupon_usage",
            "description": "View coupon usage statistics and redemption history",
            "required": [
                "auth_token"
            ],
            "optional": [
                "coupon_id",
                "date_from",
                "date_to",
                "page",
                "limit"
            ],
            "notes": "Returns usage stats, redemption records, and top performing coupons. Admin only."
        },
        "admin_raffle_prizes": {
            "method": "GET|POST|PUT|DELETE",
            "url": "\/?endpoint=admin_raffle_prizes",
            "description": "Manage prizes\/rewards for raffle draws",
            "required": [
                "auth_token"
            ],
            "optional": [
                "raffle_draw_id",
                "id",
                "prize_name",
                "quantity",
                "draw_order",
                "prize_type"
            ],
            "notes": "GET: list prizes, POST: create prize, PUT: update prize, DELETE: remove prize. Admin only."
        },
        "admin_draw_raffle": {
            "method": "POST|GET",
            "url": "\/?endpoint=admin_draw_raffle",
            "description": "Execute raffle drawing process - draw next prize winners",
            "required": [
                "auth_token"
            ],
            "optional": [
                "raffle_draw_id",
                "session_token",
                "action"
            ],
            "notes": "POST: Draw next prize, GET: Get draw status. action=start: Start session, action=complete: Complete session. Admin only."
        },
        "admin_raffle_winners": {
            "method": "GET|PUT",
            "url": "\/?endpoint=admin_raffle_winners",
            "description": "View and manage raffle winners",
            "required": [
                "auth_token"
            ],
            "optional": [
                "raffle_draw_id",
                "raffle_prize_id",
                "id",
                "action"
            ],
            "notes": "GET: list winners, PUT: action=notify (send notification), action=claim (mark as claimed). Admin only."
        },
        "admin_raffle_stats": {
            "method": "GET",
            "url": "\/?endpoint=admin_raffle_stats&raffle_draw_id=1",
            "description": "Get comprehensive raffle draw statistics and eligibility check",
            "required": [
                "auth_token",
                "raffle_draw_id"
            ],
            "notes": "Returns prizes summary, eligible entries, winners stats, next prize, and draw eligibility. Admin only."
        },
        "admin_upload_prize_image": {
            "method": "POST|DELETE",
            "url": "\/?endpoint=admin_upload_prize_image&prize_id=1",
            "description": "Upload or delete image for a raffle prize",
            "required": [
                "auth_token",
                "prize_id",
                "image (file)"
            ],
            "optional": [],
            "notes": "POST: Upload image (multipart\/form-data), DELETE: Remove image. Max 5MB, supports JPEG\/PNG\/GIF\/WebP. Admin only."
        },
        "admin_reset_raffle": {
            "method": "POST|GET",
            "url": "\/?endpoint=admin_reset_raffle",
            "description": "Reset a raffle draw for testing - deletes all winners and sessions",
            "required": [
                "auth_token",
                "raffle_draw_id"
            ],
            "optional": [],
            "notes": "POST: Reset raffle draw, GET: Preview reset impact. WARNING: Permanently deletes all winners and sessions! Admin only."
        },
        "admin_raffle_dashboard": {
            "method": "GET",
            "url": "\/?endpoint=admin_raffle_dashboard",
            "description": "Get raffle dashboard statistics and insights",
            "required": [
                "auth_token"
            ],
            "notes": "Returns overview of raffle draws, entries, and winner statistics"
        }
    }
}