# Models

## ActiveProxyItem

```json
{
  "type": "object",
  "properties": {
    "ip": {
      "type": "string"
    },
    "username": {
      "type": "string"
    },
    "password": {
      "type": "string"
    },
    "http_port": {
      "type": "integer"
    },
    "socks_port": {
      "type": "integer"
    },
    "until": {
      "type": "string",
      "description": "ISO8601/字符串日期"
    },
    "status": {
      "type": "string"
    },
    "signature": {
      "type": "string",
      "nullable": true,
      "description": "p0f 分配给IP的签名，不设置时为空"
    }
  },
  "required": [
    "ip",
    "username",
    "password",
    "http_port",
    "socks_port",
    "until",
    "status"
  ]
}
```

## ApiError

```json
{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "success",
    "message"
  ]
}
```

## AddonLine

```json
{
  "type": "object",
  "description": "订单上存储的一条附加行",
  "properties": {
    "addon_key": {
      "type": "string"
    },
    "catalog_id": {
      "type": "integer"
    },
    "qty": {
      "type": "integer",
      "description": "当期活跃单位"
    },
    "price_per_unit": {
      "type": "integer",
      "description": "购买时的单价（以美分为单位）"
    },
    "pending": {
      "description": "更改计划下次续订，或 `null`",
      "nullable": true,
      "type": "object",
      "properties": {
        "action": {
          "type": "string",
          "enum": [
            "cancel",
            "downgrade"
          ]
        },
        "next_qty": {
          "type": "integer",
          "description": "降级后目标数量"
        }
      }
    }
  }
}
```

## PurchaseRequestDcIsp

```json
{
  "type": "object",
  "description": "为数据中心/ISP 购买; 需要位置字段。",
  "properties": {
    "product": {
      "type": "string",
      "enum": [
        "Datacenter Proxy",
        "ISP Proxy"
      ]
    },
    "location": {
      "type": "string"
    },
    "cycle": {
      "type": "string"
    },
    "quantity": {
      "type": "integer",
      "minimum": 1,
      "default": 1
    },
    "promo_code": {
      "type": "string",
      "nullable": true
    },
    "auto_renewal": {
      "type": "boolean",
      "default": false
    },
    "addons": {
      "type": "array",
      "nullable": true,
      "description": "购买时附加的组件，例如 DC 或 ISP 的 `p0f_slots`",
      "items": {
        "$ref": "#/components/schemas/CreateOrderAddonRequest"
      }
    }
  },
  "required": [
    "product",
    "location",
    "cycle"
  ]
}
```

## PurchaseRequestResidentialStandard

```json
{
  "type": "object",
  "description": "购买标准住宅代理；无需位置；计费周期固定为 lifetime。",
  "properties": {
    "product": {
      "type": "string",
      "enum": [
        "Standart Residential Proxy"
      ]
    },
    "quantity": {
      "type": "integer",
      "minimum": 1,
      "default": 1
    },
    "promo_code": {
      "type": "string",
      "nullable": true
    },
    "addons": {
      "type": "array",
      "nullable": true,
      "description": "购买时附加的附加组件，例如 DC 或 ISP 的 `p0f_slots`",
      "items": {
        "$ref": "#/components/schemas/CreateOrderAddonRequest"
      }
    }
  },
  "required": [
    "product"
  ]
}
```

## PurchaseRequestResidentialPremium

```json
{
  "type": "object",
  "description": "购买高级住宅代理；无需位置；计费周期固定为 lifetime。",
  "properties": {
    "product": {
      "type": "string",
      "enum": [
        "Premium Residential Proxy"
      ]
    },
    "quantity": {
      "type": "integer",
      "minimum": 1,
      "default": 1
    },
    "promo_code": {
      "type": "string",
      "nullable": true
    },
    "addons": {
      "type": "array",
      "nullable": true,
      "description": "购买时附加的附加组件，例如 DC 或 ISP 的 `p0f_slots`",
      "items": {
        "$ref": "#/components/schemas/CreateOrderAddonRequest"
      }
    }
  },
  "required": [
    "product"
  ]
}
```

## PurchaseRequestResidentialUnmetered

```json
{
  "type": "object",
  "description": "购买不限流量住宅代理; 支持自动续订。",
  "properties": {
    "product": {
      "type": "string",
      "enum": [
        "Unmetered Residential proxy"
      ]
    },
    "cycle": {
      "type": "string"
    },
    "promo_code": {
      "type": "string",
      "nullable": true
    },
    "auto_renewal": {
      "type": "boolean",
      "default": false
    },
    "addons": {
      "type": "array",
      "nullable": true,
      "description": "购买时附加的附加组件，例如 DC 或 ISP 的 `p0f_slots`",
      "items": {
        "$ref": "#/components/schemas/CreateOrderAddonRequest"
      }
    }
  },
  "required": [
    "product",
    "cycle"
  ]
}
```

## PurchaseRequest

```json
{
  "type": "object",
  "properties": {
    "product": {
      "type": "string"
    },
    "location": {
      "type": "string",
      "nullable": true
    },
    "cycle": {
      "type": "string"
    },
    "quantity": {
      "type": "integer",
      "minimum": 1,
      "default": 1
    },
    "promo_code": {
      "type": "string",
      "nullable": true
    },
    "auto_renewal": {
      "type": "boolean",
      "default": false
    },
    "addons": {
      "type": "array",
      "nullable": true,
      "description": "购买时附加的附加组件，例如 DC 或 ISP 的 `p0f_slots`",
      "items": {
        "$ref": "#/components/schemas/CreateOrderAddonRequest"
      }
    }
  },
  "required": [
    "product",
    "cycle"
  ]
}
```

## PurchaseResponse

```json
{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean"
    },
    "message": {
      "type": "string"
    },
    "order_id": {
      "type": "integer"
    }
  },
  "required": [
    "success",
    "message",
    "order_id"
  ]
}
```

## ProductWithCycles

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "description": {
      "type": "string",
      "nullable": true
    },
    "location": {
      "type": "string",
      "nullable": true
    },
    "cycles": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "name",
    "cycles"
  ]
}
```

## AvailableCountResponse

```json
{
  "type": "object",
  "properties": {
    "country": {
      "type": "string"
    },
    "product": {
      "type": "string"
    },
    "amount": {
      "type": "integer"
    }
  },
  "required": [
    "country",
    "product",
    "amount"
  ]
}
```

## ApiMeResponse

```json
{
  "type": "object",
  "properties": {
    "email": {
      "type": "string"
    },
    "active_orders": {
      "type": "integer"
    },
    "wallet_balance": {
      "type": "integer",
      "description": "以美分为单位"
    }
  },
  "required": [
    "email",
    "active_orders",
    "wallet_balance"
  ]
}
```

## ApiSuccess

```json
{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean"
    }
  },
  "required": [
    "success"
  ]
}
```

## AvailableCountRequest

```json
{
  "type": "object",
  "properties": {
    "country": {
      "type": "string"
    },
    "product": {
      "type": "string"
    }
  },
  "required": [
    "country",
    "product"
  ]
}
```

## AddBandwidthRequest

```json
{
  "type": "object",
  "properties": {
    "amount": {
      "type": "integer",
      "description": "容量（GB）"
    },
    "promo_code": {
      "type": "string",
      "nullable": true
    }
  },
  "required": [
    "amount"
  ]
}
```

## GetSubUsersRequest

```json
{
  "type": "object",
  "properties": {
    "offset": {
      "type": "integer",
      "description": "偏移量（默认 0）"
    },
    "limit": {
      "type": "integer",
      "description": "页面大小（默认 20）"
    }
  }
}
```

## EditSubUserPayload

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    }
  },
  "required": [
    "name"
  ]
}
```

## CreateSubUserPayload

```json
{
  "type": "object",
  "properties": {
    "proxy_type": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "data": {
      "type": "integer",
      "description": "容量（GB）"
    }
  },
  "required": [
    "proxy_type",
    "name",
    "data"
  ]
}
```

## ChangeSubUserPasswordPayload

```json
{
  "type": "object",
  "properties": {
    "proxy_type": {
      "type": "string"
    }
  },
  "required": [
    "proxy_type"
  ]
}
```

## ModifyTrafficPayload

```json
{
  "type": "object",
  "properties": {
    "proxy_type": {
      "type": "string"
    },
    "data": {
      "type": "integer",
      "description": "容量（GB）"
    }
  },
  "required": [
    "proxy_type",
    "data"
  ]
}
```

## Country

```json
{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "maxLength": 10,
      "description": "ISO国家代码"
    },
    "name": {
      "type": "string",
      "maxLength": 255,
      "description": "国家名称"
    }
  },
  "required": [
    "code",
    "name"
  ]
}
```

## Region

```json
{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "maxLength": 10,
      "description": "地区代码（州/省代码）"
    },
    "name": {
      "type": "string",
      "maxLength": 255,
      "description": "地区名称（州/省名称）"
    },
    "country": {
      "$ref": "#/components/schemas/Country"
    }
  },
  "required": [
    "code",
    "name",
    "country"
  ]
}
```

## City

```json
{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "maxLength": 50,
      "description": "城市代码（通常为 slug 格式）"
    },
    "name": {
      "type": "string",
      "maxLength": 255,
      "description": "城市名称"
    },
    "country": {
      "$ref": "#/components/schemas/Country"
    },
    "region": {
      "type": "object",
      "nullable": true,
      "properties": {
        "code": {
          "type": "string",
          "maxLength": 10,
          "description": "地区代码"
        },
        "name": {
          "type": "string",
          "maxLength": 255,
          "description": "地区名称"
        }
      },
      "required": [
        "code",
        "name"
      ]
    }
  },
  "required": [
    "code",
    "name",
    "country"
  ]
}
```

## PagedCountriesResponse

```json
{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer"
    },
    "results": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Country"
      }
    }
  },
  "required": [
    "count",
    "results"
  ]
}
```

## PagedRegionsResponse

```json
{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer"
    },
    "results": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Region"
      }
    }
  },
  "required": [
    "count",
    "results"
  ]
}
```

## PagedCitiesResponse

```json
{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer"
    },
    "results": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/City"
      }
    }
  },
  "required": [
    "count",
    "results"
  ]
}
```

## Isp

```json
{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "ISP 代码，通常是一个 slug"
    },
    "name": {
      "type": "string",
      "description": "互联网服务提供商名称"
    },
    "country": {
      "$ref": "#/components/schemas/Country"
    },
    "region": {
      "type": "object",
      "nullable": true,
      "properties": {
        "code": {
          "type": "string",
          "description": "地区代码"
        },
        "name": {
          "type": "string",
          "description": "地区名称"
        }
      },
      "required": [
        "code",
        "name"
      ]
    }
  },
  "required": [
    "code",
    "name",
    "country"
  ]
}
```

## PagedIspsResponse

```json
{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer"
    },
    "results": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Isp"
      }
    }
  },
  "required": [
    "count",
    "results"
  ]
}
```

## CreateOrderAddonRequest

```json
{
  "type": "object",
  "properties": {
    "addon_key": {
      "type": "string",
      "example": "p0f_slots"
    },
    "qty": {
      "type": "integer",
      "minimum": 1
    }
  },
  "required": [
    "addon_key",
    "qty"
  ]
}
```