{
  "api_base_url": "http://your-domain.com/api",
  "endpoints": {
    "health_check": {
      "method": "GET",
      "url": "/api/health/",
      "authentication": "None",
      "request": null,
      "response_success": {
        "status": "healthy",
        "timestamp": "2025-11-13T10:30:00Z",
        "version": "1.0.0",
        "service": "kitonga-wifi-billing"
      },
      "response_error": {
        "status": "unhealthy",
        "timestamp": "2025-11-13T10:30:00Z",
        "error": "Database connection failed"
      }
    },
    "admin_login": {
      "method": "POST",
      "url": "/api/admin/login/",
      "authentication": "None",
      "request": {
        "username": "admin",
        "password": "yourpassword"
      },
      "response_success": {
        "success": true,
        "message": "Login successful",
        "user": {
          "id": 1,
          "username": "admin",
          "email": "admin@example.com",
          "first_name": "Admin",
          "last_name": "User",
          "is_staff": true,
          "is_superuser": true,
          "last_login": "2025-11-13T10:00:00Z",
          "date_joined": "2025-01-01T00:00:00Z"
        },
        "token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
        "admin_access_token": "your-simple-admin-token"
      },
      "response_error": {
        "success": false,
        "message": "Invalid username or password"
      }
    },
    "admin_logout": {
      "method": "POST",
      "url": "/api/admin/logout/",
      "authentication": "Session or Token",
      "request": {},
      "response_success": {
        "success": true,
        "message": "Logout successful"
      }
    },
    "admin_profile": {
      "method": "GET",
      "url": "/api/admin/profile/",
      "authentication": "Token",
      "headers": {
        "Authorization": "Token a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
      },
      "response_success": {
        "success": true,
        "user": {
          "id": 1,
          "username": "admin",
          "email": "admin@example.com",
          "first_name": "Admin",
          "last_name": "User",
          "is_staff": true,
          "is_superuser": true,
          "last_login": "2025-11-13T10:00:00Z",
          "date_joined": "2025-01-01T00:00:00Z"
        },
        "is_authenticated": true
      }
    },
    "admin_change_password": {
      "method": "POST",
      "url": "/api/admin/change-password/",
      "authentication": "Token",
      "request": {
        "current_password": "oldpassword",
        "new_password": "newpassword123",
        "confirm_password": "newpassword123"
      },
      "response_success": {
        "success": true,
        "message": "Password changed successfully",
        "token": "new_token_key_here"
      }
    },
    "create_admin_user": {
      "method": "POST",
      "url": "/api/admin/create/",
      "authentication": "None (if no admins exist) or Superuser Token",
      "request": {
        "username": "newadmin",
        "password": "securepassword",
        "email": "newadmin@example.com",
        "first_name": "New",
        "last_name": "Admin"
      },
      "response_success": {
        "success": true,
        "message": "Admin user created successfully",
        "user": {
          "id": 2,
          "username": "newadmin",
          "email": "newadmin@example.com",
          "first_name": "New",
          "last_name": "Admin",
          "is_staff": true,
          "is_superuser": false
        }
      }
    },
    "list_users": {
      "method": "GET",
      "url": "/api/admin/users/",
      "authentication": "Admin Token",
      "headers": {
        "X-Admin-Token": "your-simple-admin-token"
      },
      "query_params": {
        "phone_number": "255772236727",
        "is_active": "true",
        "page": 1,
        "page_size": 20
      },
      "response_success": {
        "success": true,
        "users": [
          {
            "id": 42,
            "phone_number": "255772236727",
            "is_active": true,
            "created_at": "2025-11-01T08:00:00Z",
            "paid_until": "2025-11-14T08:00:00Z",
            "has_active_access": true,
            "max_devices": 3,
            "total_payments": 15000,
            "device_count": 2,
            "payment_count": 5,
            "last_payment": {
              "amount": "5000",
              "bundle_name": "Daily Pass",
              "completed_at": "2025-11-13T10:00:00Z"
            }
          }
        ],
        "pagination": {
          "total": 150,
          "page": 1,
          "page_size": 20,
          "total_pages": 8
        }
      }
    },
    "get_user_detail": {
      "method": "GET",
      "url": "/api/admin/users/{user_id}/",
      "authentication": "Admin Token",
      "response_success": {
        "success": true,
        "user": {
          "id": 42,
          "phone_number": "255772236727",
          "is_active": true,
          "created_at": "2025-11-01T08:00:00Z",
          "has_active_access": true,
          "payments": [
            {
              "id": 101,
              "amount": "5000",
              "status": "completed",
              "bundle_name": "Daily Pass",
              "order_reference": "ORD-123456",
              "created_at": "2025-11-13T10:00:00Z",
              "completed_at": "2025-11-13T10:02:00Z"
            }
          ],
          "devices": [
            {
              "id": 1,
              "mac_address": "AA:BB:CC:DD:EE:FF",
              "device_name": "iPhone 12",
              "is_active": true,
              "last_seen": "2025-11-13T10:30:00Z",
              "first_seen": "2025-11-01T08:15:00Z"
            }
          ],
          "access_logs": [
            {
              "id": 500,
              "access_granted": true,
              "denial_reason": null,
              "ip_address": "192.168.88.100",
              "mac_address": "AA:BB:CC:DD:EE:FF",
              "timestamp": "2025-11-13T10:30:00Z"
            }
          ],
          "statistics": {
            "total_payments": 5,
            "total_spent": 15000,
            "device_count": 2,
            "active_devices": 1
          }
        }
      }
    },
    "update_user": {
      "method": "PUT",
      "url": "/api/admin/users/{user_id}/",
      "authentication": "Admin Token",
      "request": {
        "is_active": false,
        "phone_number": "255772236728"
      },
      "response_success": {
        "success": true,
        "message": "User updated successfully",
        "user": {
          "id": 42,
          "phone_number": "255772236728",
          "is_active": false,
          "has_active_access": false
        }
      }
    },
    "delete_user": {
      "method": "DELETE",
      "url": "/api/admin/users/{user_id}/",
      "authentication": "Admin Token",
      "response_success": {
        "success": true,
        "message": "User 255772236727 deleted successfully"
      }
    },
    "list_payments": {
      "method": "GET",
      "url": "/api/admin/payments/",
      "authentication": "Admin Token",
      "query_params": {
        "status": "completed",
        "phone_number": "255772236727",
        "date_from": "2025-11-01T00:00:00Z",
        "date_to": "2025-11-13T23:59:59Z",
        "bundle_id": 1,
        "page": 1,
        "page_size": 20
      },
      "response_success": {
        "success": true,
        "payments": [
          {
            "id": 101,
            "phone_number": "255772236727",
            "amount": "5000",
            "status": "completed",
            "order_reference": "ORD-123456",
            "bundle_name": "Daily Pass",
            "bundle_id": 1,
            "created_at": "2025-11-13T10:00:00Z",
            "completed_at": "2025-11-13T10:02:00Z",
            "user_id": 42,
            "payment_reference": "PAY-789012",
            "transaction_id": "TXN-345678",
            "payment_channel": "M-Pesa"
          }
        ],
        "pagination": {
          "total": 250,
          "page": 1,
          "page_size": 20,
          "total_pages": 13
        },
        "summary": {
          "total_amount": "125000",
          "pending_amount": "15000",
          "completed_count": 200,
          "pending_count": 30,
          "failed_count": 20
        }
      }
    },
    "get_payment_detail": {
      "method": "GET",
      "url": "/api/admin/payments/{payment_id}/",
      "authentication": "Admin Token",
      "response_success": {
        "success": true,
        "payment": {
          "id": 101,
          "phone_number": "255772236727",
          "amount": "5000",
          "status": "completed",
          "order_reference": "ORD-123456",
          "payment_reference": "PAY-789012",
          "transaction_id": "TXN-345678",
          "payment_channel": "M-Pesa",
          "bundle": {
            "id": 1,
            "name": "Daily Pass",
            "price": "5000",
            "duration_hours": 24,
            "description": "24 hours unlimited access"
          },
          "user": {
            "id": 42,
            "phone_number": "255772236727",
            "is_active": true,
            "has_active_access": true
          },
          "created_at": "2025-11-13T10:00:00Z",
          "completed_at": "2025-11-13T10:02:00Z",
          "webhook_logs": [
            {
              "id": 50,
              "event_type": "payment.completed",
              "payment_status": "SUCCESS",
              "amount": "5000",
              "transaction_id": "TXN-345678",
              "received_at": "2025-11-13T10:02:00Z",
              "processed_at": "2025-11-13T10:02:05Z",
              "processing_status": "processed"
            }
          ]
        }
      }
    },
    "refund_payment": {
      "method": "POST",
      "url": "/api/admin/payments/{payment_id}/refund/",
      "authentication": "Admin Token",
      "response_success": {
        "success": true,
        "message": "Payment ORD-123456 refunded successfully"
      }
    },
    "manage_bundles": {
      "method": "GET",
      "url": "/api/admin/bundles/",
      "authentication": "Admin Token",
      "response_success": {
        "success": true,
        "bundles": [
          {
            "id": 1,
            "name": "Daily Pass",
            "description": "24 hours unlimited access",
            "price": "5000",
            "duration_hours": 24,
            "is_active": true,
            "display_order": 1,
            "total_purchases": 150,
            "revenue": "750000"
          },
          {
            "id": 2,
            "name": "Weekly Pass",
            "description": "7 days unlimited access",
            "price": "20000",
            "duration_hours": 168,
            "is_active": true,
            "display_order": 2,
            "total_purchases": 50,
            "revenue": "1000000"
          }
        ]
      }
    },
    "create_bundle": {
      "method": "POST",
      "url": "/api/admin/bundles/",
      "authentication": "Admin Token",
      "request": {
        "name": "Monthly Pass",
        "description": "30 days unlimited access",
        "price": 50000,
        "duration_hours": 720,
        "display_order": 3,
        "is_active": true
      },
      "response_success": {
        "success": true,
        "message": "Bundle created successfully",
        "bundle": {
          "id": 3,
          "name": "Monthly Pass",
          "price": "50000",
          "duration_hours": 720
        }
      }
    },
    "get_bundle_detail": {
      "method": "GET",
      "url": "/api/admin/bundles/{bundle_id}/",
      "authentication": "Admin Token",
      "response_success": {
        "success": true,
        "bundle": {
          "id": 1,
          "name": "Daily Pass",
          "description": "24 hours unlimited access",
          "price": "5000",
          "duration_hours": 24,
          "is_active": true,
          "display_order": 1,
          "statistics": {
            "total_purchases": 150,
            "total_revenue": "750000",
            "recent_purchases": [
              {
                "phone_number": "255772236727",
                "amount": "5000",
                "completed_at": "2025-11-13T10:00:00Z"
              }
            ]
          }
        }
      }
    },
    "update_bundle": {
      "method": "PUT",
      "url": "/api/admin/bundles/{bundle_id}/",
      "authentication": "Admin Token",
      "request": {
        "name": "Daily Pass - Updated",
        "price": 6000,
        "is_active": false
      },
      "response_success": {
        "success": true,
        "message": "Bundle updated successfully",
        "bundle": {
          "id": 1,
          "name": "Daily Pass - Updated",
          "price": "6000",
          "is_active": false
        }
      }
    },
    "delete_bundle": {
      "method": "DELETE",
      "url": "/api/admin/bundles/{bundle_id}/",
      "authentication": "Admin Token",
      "response_success": {
        "success": true,
        "message": "Bundle \"Daily Pass\" deleted successfully"
      }
    },
    "system_settings": {
      "method": "GET",
      "url": "/api/admin/settings/",
      "authentication": "Admin Token",
      "response_success": {
        "success": true,
        "settings": {
          "mikrotik": {
            "router_ip": "192.168.88.1",
            "username": "admin",
            "hotspot_name": "hotspot1",
            "api_port": 8728,
            "connection_status": "Unknown"
          },
          "clickpesa": {
            "api_key_configured": true,
            "webhook_url": "https://yourdomain.com/api/webhooks/clickpesa/",
            "environment": "sandbox"
          },
          "nextsms": {
            "api_key_configured": true,
            "sender_id": "KITONGA"
          },
          "system": {
            "debug_mode": false,
            "allowed_hosts": ["*"],
            "time_zone": "Africa/Dar_es_Salaam",
            "language_code": "en-us"
          }
        }
      }
    },
    "system_status": {
      "method": "GET",
      "url": "/api/admin/status/",
      "authentication": "Admin Token",
      "response_success": {
        "success": true,
        "status": {
          "database_status": "OK",
          "mikrotik_status": "OK",
          "uptime": "Unknown",
          "memory_usage": "Unknown",
          "disk_usage": "Unknown",
          "active_users": 25,
          "payments_today": 10,
          "revenue_today": 50000,
          "payments_week": 75,
          "revenue_week": 375000,
          "total_users": 250,
          "active_bundles": 3,
          "pending_payments": 5
        },
        "timestamp": "2025-11-13T10:30:00Z"
      }
    },
    "mikrotik_configuration": {
      "method": "GET",
      "url": "/api/admin/mikrotik/config/",
      "authentication": "Admin Token",
      "response_success": {
        "success": true,
        "configuration": {
          "router_ip": "192.168.88.1",
          "username": "admin",
          "password_configured": true,
          "api_port": 8728,
          "hotspot_name": "hotspot1",
          "connection_timeout": 10,
          "max_login_attempts": 3
        }
      }
    },
    "test_mikrotik_connection": {
      "method": "POST",
      "url": "/api/admin/mikrotik/test/",
      "authentication": "Admin Token",
      "request": {
        "router_ip": "192.168.88.1",
        "username": "admin",
        "password": "yourpassword",
        "api_port": 8728
      },
      "response_success": {
        "success": true,
        "message": "Connection test completed",
        "router_info": {
          "board_name": "hAP lite",
          "version": "6.49.6",
          "architecture": "mipsbe"
        },
        "error": null
      }
    },
    "mikrotik_router_info": {
      "method": "GET",
      "url": "/api/admin/mikrotik/info/",
      "authentication": "Admin Token",
      "response_success": {
        "success": true,
        "router_info": {
          "board_name": "hAP lite",
          "version": "6.49.6",
          "architecture": "mipsbe",
          "uptime": "1w2d3h",
          "cpu_load": "5%"
        }
      }
    },
    "mikrotik_active_users": {
      "method": "GET",
      "url": "/api/admin/mikrotik/active-users/",
      "authentication": "Admin Token",
      "response_success": {
        "success": true,
        "active_users": [
          {
            "username": "255772236727",
            "ip_address": "192.168.88.100",
            "mac_address": "AA:BB:CC:DD:EE:FF",
            "uptime": "1h30m",
            "bytes_in": "1048576",
            "bytes_out": "2097152"
          }
        ],
        "total_count": 1
      }
    },
    "mikrotik_disconnect_user": {
      "method": "POST",
      "url": "/api/admin/mikrotik/disconnect/",
      "authentication": "Admin Token",
      "request": {
        "username": "255772236727"
      },
      "response_success": {
        "success": true,
        "message": "User 255772236727 disconnected successfully"
      }
    },
    "mikrotik_disconnect_all_users": {
      "method": "POST",
      "url": "/api/admin/mikrotik/disconnect-all/",
      "authentication": "Admin Token",
      "response_success": {
        "success": true,
        "message": "Successfully disconnected 25 users",
        "disconnected_count": 25
      }
    },
    "verify_access": {
      "method": "POST",
      "url": "/api/verify-access/",
      "authentication": "None",
      "description": "Core endpoint for captive portal - checks access and connects/disconnects user",
      "request": {
        "phone_number": "255772236727",
        "mac_address": "AA:BB:CC:DD:EE:FF",
        "ip_address": "192.168.88.100"
      },
      "response_grant_access": {
        "success": true,
        "has_access": true,
        "access_type": "payment",
        "paid_until": "2025-11-14T10:00:00Z",
        "remaining_seconds": 82800,
        "device_count": 1,
        "max_devices": 3,
        "user": {
          "id": 42,
          "phone_number": "255772236727"
        },
        "mikrotik_connection": {
          "action": "grant",
          "success": true,
          "message": "Hotspot user created and allowed by MAC",
          "username": "255772236727",
          "password": "236727",
          "chap": null,
          "redirect_url": "http://example.com"
        }
      },
      "response_already_connected": {
        "success": true,
        "has_access": true,
        "access_type": "voucher",
        "paid_until": "2025-11-14T10:00:00Z",
        "remaining_seconds": 82800,
        "device_count": 1,
        "max_devices": 2,
        "user": {
          "id": 99,
          "phone_number": "255700111222"
        },
        "mikrotik_connection": {
          "action": "none",
          "success": true,
          "message": "User already active on router"
        }
      },
      "response_deny_access": {
        "success": false,
        "has_access": false,
        "denial_reason": "Subscription expired",
        "user": {
          "id": 77,
          "phone_number": "255700000000"
        },
        "mikrotik_connection": {
          "action": "revoke",
          "success": true,
          "message": "User removed from hotspot and MAC unbypassed"
        }
      },
      "response_device_limit": {
        "success": false,
        "has_access": false,
        "denial_reason": "Maximum device limit reached (2/2)",
        "user": {
          "id": 88,
          "phone_number": "255700222333"
        },
        "mikrotik_connection": {
          "action": "revoke",
          "success": true,
          "message": "Device limit exceeded - access denied"
        }
      },
      "response_user_not_found": {
        "success": false,
        "has_access": false,
        "denial_reason": "User not found. Please make a payment first."
      },
      "response_validation_error": {
        "phone_number": ["This field is required."],
        "mac_address": ["Enter a valid MAC address."]
      }
    },
    "initiate_payment": {
      "method": "POST",
      "url": "/api/payments/initiate/",
      "authentication": "None",
      "request": {
        "phone_number": "255772236727",
        "bundle_id": 1
      },
      "response_success": {
        "success": true,
        "message": "Payment initiated successfully",
        "payment": {
          "id": 101,
          "order_reference": "ORD-123456",
          "amount": "5000",
          "status": "pending",
          "bundle": {
            "id": 1,
            "name": "Daily Pass",
            "duration_hours": 24
          }
        },
        "checkout_url": "https://checkout.clickpesa.com/xyz"
      }
    },
    "check_payment_status": {
      "method": "GET",
      "url": "/api/payments/{order_reference}/status/",
      "authentication": "None",
      "response_success": {
        "success": true,
        "payment": {
          "order_reference": "ORD-123456",
          "status": "completed",
          "amount": "5000",
          "bundle_name": "Daily Pass",
          "completed_at": "2025-11-13T10:02:00Z"
        }
      }
    },
    "list_bundles_public": {
      "method": "GET",
      "url": "/api/bundles/",
      "authentication": "None",
      "response_success": {
        "success": true,
        "bundles": [
          {
            "id": 1,
            "name": "Daily Pass",
            "description": "24 hours unlimited access",
            "price": "5000",
            "duration_hours": 24,
            "display_order": 1
          },
          {
            "id": 2,
            "name": "Weekly Pass",
            "description": "7 days unlimited access",
            "price": "20000",
            "duration_hours": 168,
            "display_order": 2
          }
        ]
      }
    },
    "generate_vouchers": {
      "method": "POST",
      "url": "/api/admin/vouchers/generate/",
      "authentication": "Admin Token",
      "request": {
        "bundle_id": 1,
        "count": 10,
        "valid_days": 30
      },
      "response_success": {
        "success": true,
        "message": "10 vouchers generated successfully",
        "vouchers": [
          {
            "id": 1,
            "code": "WIFI-ABC123",
            "bundle_name": "Daily Pass",
            "is_redeemed": false,
            "expires_at": "2025-12-13T10:00:00Z"
          }
        ]
      }
    },
    "redeem_voucher": {
      "method": "POST",
      "url": "/api/vouchers/redeem/",
      "authentication": "None",
      "request": {
        "phone_number": "255772236727",
        "voucher_code": "WIFI-ABC123",
        "mac_address": "AA:BB:CC:DD:EE:FF",
        "ip_address": "192.168.88.100"
      },
      "response_success": {
        "success": true,
        "message": "Voucher redeemed successfully",
        "user": {
          "phone_number": "255772236727",
          "paid_until": "2025-11-14T10:00:00Z",
          "has_active_access": true
        },
        "bundle": {
          "name": "Daily Pass",
          "duration_hours": 24
        },
        "mikrotik_connection": {
          "action": "grant",
          "success": true,
          "message": "Access granted via MikroTik",
          "username": "255772236727",
          "password": "236727"
        }
      },
      "response_error": {
        "success": false,
        "message": "Invalid voucher code"
      }
    },
    "list_vouchers": {
      "method": "GET",
      "url": "/api/admin/vouchers/",
      "authentication": "Admin Token",
      "query_params": {
        "bundle_id": 1,
        "is_redeemed": "false",
        "page": 1,
        "page_size": 20
      },
      "response_success": {
        "success": true,
        "vouchers": [
          {
            "id": 1,
            "code": "WIFI-ABC123",
            "bundle": {
              "id": 1,
              "name": "Daily Pass"
            },
            "is_redeemed": false,
            "redeemed_by": null,
            "redeemed_at": null,
            "created_at": "2025-11-13T10:00:00Z",
            "expires_at": "2025-12-13T10:00:00Z"
          }
        ],
        "pagination": {
          "total": 50,
          "page": 1,
          "page_size": 20,
          "total_pages": 3
        }
      }
    }
  },
  "authentication_methods": {
    "admin_token_header": {
      "header_name": "X-Admin-Token",
      "header_value": "your-simple-admin-token-from-settings"
    },
    "user_token_header": {
      "header_name": "Authorization",
      "header_value": "Token a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
    }
  },
  "common_error_responses": {
    "400_bad_request": {
      "success": false,
      "message": "Invalid request data",
      "errors": {
        "field_name": ["Error message"]
      }
    },
    "401_unauthorized": {
      "success": false,
      "message": "Authentication required"
    },
    "403_forbidden": {
      "success": false,
      "message": "Access denied. Admin privileges required."
    },
    "404_not_found": {
      "success": false,
      "message": "Resource not found"
    },
    "500_internal_server_error": {
      "success": false,
      "message": "Internal server error"
    }
  },
  "frontend_fetch_examples": {
    "verify_access_fetch": {
      "code": "fetch('/api/verify-access/', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ phone_number: '255772236727', mac_address: 'AA:BB:CC:DD:EE:FF', ip_address: '192.168.88.100' }) })"
    },
    "admin_login_fetch": {
      "code": "fetch('/api/admin/login/', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ username: 'admin', password: 'password' }) })"
    },
    "list_users_fetch": {
      "code": "fetch('/api/admin/users/', { headers: { 'X-Admin-Token': 'your-token' } })"
    }
  }
}