# Residential Proxies

住宅代理的操作

## 购买额外流量（住宅）

`POST /user/api/orders/{id}/add-bandwidth`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "购买额外流量（住宅）",
  "parameters": [
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "integer"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AddBandwidthRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "成功的",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "message": {
                "type": "string",
                "example": "Order paid successfully"
              }
            },
            "required": [
              "success",
              "message"
            ]
          }
        }
      }
    }
  }
}
```

## 账户所有者流量

`GET /user/api/proxies/profile`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "账户所有者流量",
  "description": "返回给定代理类型的父账户自己的总数据和剩余数据，在父订单中聚合。与子用户端点不同，这反映了帐户所有者的数据，而不是子用户的数据。",
  "parameters": [
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "代理类型（标准 | 高级）",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "成功",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "type": "integer",
                "description": "分配的数据总量（以字节为单位）"
              },
              "data_remain": {
                "type": "integer",
                "description": "剩余数据（以字节为单位）"
              },
              "data_spent": {
                "type": "integer",
                "description": "消耗的数据（以字节为单位）"
              },
              "proxy_password": {
                "type": "string",
                "description": "父帐户的代理密码"
              }
            },
            "required": [
              "success",
              "data",
              "data_remain",
              "data_spent",
              "proxy_password"
            ]
          }
        }
      }
    },
    "400": {
      "description": "用户驻留未设置/代理类型无效",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "未经授权",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  }
}
```

## 子用户列表

`GET /user/api/proxies/sub-users`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "子用户列表",
  "parameters": [
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "代理类型（标准 | 高级）",
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "offset",
      "required": false,
      "schema": {
        "type": "integer"
      }
    },
    {
      "in": "query",
      "name": "limit",
      "required": false,
      "schema": {
        "type": "integer"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "成功的",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "count": {
                "type": "integer",
                "description": "分页前子用户总数"
              },
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "user_id": {
                      "type": "string"
                    },
                    "first_name": {
                      "type": "string"
                    },
                    "proxy_password": {
                      "type": "string"
                    },
                    "data": {
                      "type": "integer"
                    },
                    "data_spent": {
                      "type": "integer"
                    },
                    "data_remain": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "user_id",
                    "first_name",
                    "proxy_password",
                    "data",
                    "data_spent",
                    "data_remain"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}
```

## 通过ID获取子用户

`GET /user/api/proxies/sub-user/{user_id}`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "通过ID获取子用户",
  "parameters": [
    {
      "in": "path",
      "name": "user_id",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "代理类型（标准 | 高级）",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "成功的",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "first_name": {
                      "type": "string"
                    },
                    "proxy_password": {
                      "type": "string"
                    },
                    "data": {
                      "type": "integer"
                    },
                    "data_spent": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "first_name",
                    "proxy_password",
                    "data",
                    "data_spent"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}
```

## 删除子用户

`DELETE /user/api/proxies/sub-user/{user_id}`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "删除子用户",
  "parameters": [
    {
      "in": "path",
      "name": "user_id",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "成功的",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "message": {
                "type": "string",
                "example": "Sub user deleted successfully"
              }
            },
            "required": [
              "success",
              "message"
            ]
          }
        }
      }
    }
  }
}
```

## 编辑子用户（名称/包）

`PATCH /user/api/proxies/sub-user/{user_id}`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "编辑子用户（名称/包）",
  "parameters": [
    {
      "in": "path",
      "name": "user_id",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "代理类型（标准 | 高级）",
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/EditSubUserPayload"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "成功的",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "message": {
                "type": "string",
                "example": "Sub user edited successfully"
              }
            },
            "required": [
              "success",
              "message"
            ]
          }
        }
      }
    }
  }
}
```

## 创建子用户

`POST /user/api/proxies/sub-user`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "创建子用户",
  "parameters": [
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "代理类型（标准 | 高级）",
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "data": {
              "type": "integer"
            }
          },
          "required": [
            "name",
            "data"
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "成功的",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "user_id": {
                      "type": "string"
                    },
                    "first_name": {
                      "type": "string"
                    },
                    "proxy_password": {
                      "type": "string"
                    },
                    "data": {
                      "type": "integer"
                    },
                    "data_spent": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "user_id",
                    "first_name",
                    "proxy_password",
                    "data",
                    "data_spent"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}
```

## 给子用户添加流量

`POST /user/api/proxies/sub-user/{user_id}/data/add`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "给子用户添加流量",
  "parameters": [
    {
      "in": "path",
      "name": "user_id",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "代理类型（标准 | 高级）",
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "data": {
              "type": "integer",
              "description": "容量（GB）"
            }
          },
          "required": [
            "data"
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "成功的",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "message": {
                "type": "string",
                "example": "Traffic added to sub user successfully"
              }
            },
            "required": [
              "success",
              "message"
            ]
          }
        }
      }
    }
  }
}
```

## 扣除子用户流量

`POST /user/api/proxies/sub-user/{user_id}/data/subtract`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "扣除子用户流量",
  "parameters": [
    {
      "in": "path",
      "name": "user_id",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "代理类型（标准 | 高级）",
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "data": {
              "type": "integer",
              "description": "容量（GB）"
            }
          },
          "required": [
            "data"
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "成功的",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "message": {
                "type": "string",
                "example": "Traffic subtracted from sub user successfully"
              }
            },
            "required": [
              "success",
              "message"
            ]
          }
        }
      }
    }
  }
}
```

## 修改子用户密码

`POST /user/api/proxies/sub-user/{user_id}/password`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "修改子用户密码",
  "parameters": [
    {
      "in": "path",
      "name": "user_id",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "代理类型（标准 | 高级）",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "成功的",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "message": {
                "type": "string",
                "example": "Sub user password changed successfully"
              }
            },
            "required": [
              "success",
              "message"
            ]
          }
        }
      }
    }
  }
}
```

## 国家列表

`GET /user/api/proxies/countries`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "国家列表",
  "parameters": [
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "代理类型（标准 | 高级）",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "成功的",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PagedCountriesResponse"
          }
        }
      }
    }
  }
}
```

## 地区列表

`GET /user/api/proxies/regions`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "地区列表",
  "parameters": [
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "代理类型（标准 | 高级）",
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "country_code",
      "required": true,
      "description": "ISO国家代码",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "成功的",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PagedRegionsResponse"
          }
        }
      }
    }
  }
}
```

## 城市列表

`GET /user/api/proxies/cities`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "城市列表",
  "parameters": [
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "代理类型（标准 | 高级）",
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "country_code",
      "required": true,
      "description": "ISO国家代码",
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "region_code",
      "required": true,
      "description": "地区代码（州/省）",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "成功的",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PagedCitiesResponse"
          }
        }
      }
    }
  }
}
```

## 列出 ISP

`GET /user/api/proxies/isps`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "列出 ISP",
  "description": "城市内可用的互联网提供商；继国家、地区、城市之后的第四个目标级别。与其他位置端点不同，这个端点需要完整的链：`country_code`、`region_code` 和 `city_code` 都是必需的，因为上游 ISP 与城市绑定。仅高级套餐：不为标准套餐和无限制套餐维护 ISP 目录，任何其他 `proxy_type` 都会被拒绝并返回 400。仅列出主要城市的 ISP，因此对于较小的城市，带有 `count: 0` 的空 `results` 是正常答案。",
  "parameters": [
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "必须为 `premium`；ISP 定向仅适用于 premium 套餐。",
      "schema": {
        "type": "string",
        "enum": [
          "premium"
        ]
      }
    },
    {
      "in": "query",
      "name": "country_code",
      "required": true,
      "description": "ISO国家代码",
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "region_code",
      "required": true,
      "description": "地区或州代码",
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "city_code",
      "required": true,
      "description": "来自 GET /user/api/proxies/cities 的城市代码",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "成功",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PagedIspsResponse"
          }
        }
      }
    },
    "400": {
      "description": "proxy_type 不是 `premium`，未设置用户常驻，或者用户没有对该包的有效订单",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          },
          "examples": {
            "notPremium": {
              "value": {
                "success": false,
                "message": "ISP targeting is available for the premium package only"
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "未经授权",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  }
}
```