# Datacenter & ISP Proxies

数据中心和 ISP 代理的操作

## 获取订单中的活动代理

`GET /user/api/proxies/active`

```json
{
  "tags": [
    "Datacenter & ISP Proxies"
  ],
  "summary": "获取订单中的活动代理",
  "parameters": [
    {
      "in": "query",
      "name": "order_id",
      "required": true,
      "schema": {
        "type": "integer"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "代理列表",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ActiveProxyItem"
                }
              },
              "order_tag": {
                "type": "string",
                "nullable": true
              }
            },
            "required": [
              "success",
              "data"
            ]
          }
        }
      }
    },
    "403": {
      "description": "此订单无法使用该方法",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  }
}
```

## 设置按 IP 删除 (del-np)

`POST /user/api/orders/{order_id}/del-np/set`

```json
{
  "tags": [
    "Datacenter & ISP Proxies"
  ],
  "summary": "设置按 IP 删除 (del-np)",
  "description": "仅适用于数据中心和 ISP 代理。更新后，重新计算订单 `quantity` 和 `price_paid`。",
  "parameters": [
    {
      "in": "path",
      "name": "order_id",
      "required": true,
      "schema": {
        "type": "integer"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "items": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "ip": {
                    "type": "string"
                  },
                  "value": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "ip",
                  "value"
                ]
              }
            }
          },
          "required": [
            "items"
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "成功",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "验证错误/不是 DC-ISP/keep=0",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  }
}
```

## 设置 IP 操作系统指纹

`POST /user/api/orders/{order_id}/signature/set`

```json
{
  "tags": [
    "Datacenter & ISP Proxies"
  ],
  "summary": "设置 IP 操作系统指纹",
  "description": "为一个或多个代理 IP 设置操作系统指纹签名。  \n订单必须启用 `p0f_slots` 组件。\n\n每个设置了签名的 IP 会永久占用一个槽位。修改已有签名 IP 的操作系统值不会占用额外槽位。\n\n**可用的签名值：**\n\n| 值 | 操作系统 |\n| --- | --- |\n| `ios` | iOS |\n| `macos` | macOS |\n| `android` | Android |\n| `linux` | Linux |\n| `win10` | Windows 10 |\n| `win11` | Windows 11 |",
  "parameters": [
    {
      "in": "path",
      "name": "order_id",
      "required": true,
      "schema": {
        "type": "integer"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "items"
          ],
          "properties": {
            "items": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "ip",
                  "signature"
                ],
                "properties": {
                  "ip": {
                    "type": "string"
                  },
                  "signature": {
                    "type": "string",
                    "description": "要欺骗的操作系统标识符。",
                    "enum": [
                      "ios",
                      "macos",
                      "android",
                      "linux",
                      "win10",
                      "win11"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "成功",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "message": {
                "type": "string"
              },
              "updated": {
                "type": "integer",
                "description": "更新的IP数量"
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "验证错误或插槽不足",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  }
}
```

## 计算附加成本

`GET /user/api/orders/{order_id}/addons/calculate`

```json
{
  "tags": [
    "Datacenter & ISP Proxies"
  ],
  "summary": "计算附加成本",
  "description": "返回为活动数据中心/ISP 订单购买给定附加组件的额外单位的价格预览。目前唯一支持的附加密钥是 `p0f_slots`；操作系统指纹签名槽。",
  "parameters": [
    {
      "in": "path",
      "name": "order_id",
      "required": true,
      "description": "订单号",
      "schema": {
        "type": "integer"
      }
    },
    {
      "in": "query",
      "name": "addon_key",
      "required": true,
      "description": "附加标识符（例如 `p0f_slots`）",
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "add_qty",
      "required": true,
      "description": "要添加的单位数量",
      "schema": {
        "type": "integer",
        "minimum": 1
      }
    }
  ],
  "responses": {
    "200": {
      "description": "价格预览",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "addon_key": {
                "type": "string"
              },
              "catalog_id": {
                "type": "integer"
              },
              "price_per_unit": {
                "type": "integer",
                "description": "每单位价格（美分）"
              },
              "current_qty": {
                "type": "integer"
              },
              "add_qty": {
                "type": "integer"
              },
              "new_qty": {
                "type": "integer"
              },
              "add_total": {
                "type": "integer",
                "description": "本次购买的总费用（以美分为单位）"
              }
            }
          }
        }
      }
    }
  }
}
```

## 购买附加组件

`POST /user/api/orders/{order_id}/addons/purchase`

```json
{
  "tags": [
    "Datacenter & ISP Proxies"
  ],
  "summary": "购买附加组件",
  "description": "立即从钱包扣款，并将指定数量的组件添加到订单。订单状态必须为 **active**。目前只有 `p0f_slots` 可用。",
  "parameters": [
    {
      "in": "path",
      "name": "order_id",
      "required": true,
      "description": "订单号",
      "schema": {
        "type": "integer"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "addon_key",
            "add_qty"
          ],
          "properties": {
            "addon_key": {
              "type": "string"
            },
            "add_qty": {
              "type": "integer",
              "minimum": 1
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "已购买附加组件",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "message": {
                "type": "string"
              },
              "addons_price_paid": {
                "type": "integer",
                "description": "该订单的累计附加成本（分）"
              },
              "addons": {
                "type": "array",
                "description": "订单中存储的更新附加列表",
                "items": {
                  "$ref": "#/components/schemas/AddonLine"
                }
              }
            }
          }
        }
      }
    }
  }
}
```

## 安排附加降级

`POST /user/api/orders/{order_id}/addons/schedule`

```json
{
  "tags": [
    "Datacenter & ISP Proxies"
  ],
  "summary": "安排附加降级",
  "description": "安排组件在下一个续订周期 **降级**。新数量必须低于当前数量。更改保存为 `pending` 标记，并在订单续订时自动应用。",
  "parameters": [
    {
      "in": "path",
      "name": "order_id",
      "required": true,
      "description": "订单号",
      "schema": {
        "type": "integer"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "addon_key",
            "action",
            "next_qty"
          ],
          "properties": {
            "addon_key": {
              "type": "string"
            },
            "action": {
              "type": "string",
              "enum": [
                "downgrade"
              ]
            },
            "next_qty": {
              "type": "integer",
              "description": "续订后的目标数量。必须小于当前数量。",
              "minimum": 1
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "已安排降级",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "message": {
                "type": "string"
              },
              "addons": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/AddonLine"
                }
              }
            }
          }
        }
      }
    }
  }
}
```

## 取消已安排的降级

`POST /user/api/orders/{order_id}/addons/schedule/cancel`

```json
{
  "tags": [
    "Datacenter & ISP Proxies"
  ],
  "summary": "取消已安排的降级",
  "description": "取消通过 schedule 接口设置的待处理降级。",
  "parameters": [
    {
      "in": "path",
      "name": "order_id",
      "required": true,
      "description": "订单号",
      "schema": {
        "type": "integer"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "addon_key"
          ],
          "properties": {
            "addon_key": {
              "type": "string"
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "待降级已清除",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "message": {
                "type": "string"
              },
              "addons": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/AddonLine"
                }
              }
            }
          }
        }
      }
    }
  }
}
```