{
  "openapi": "3.1.0",
  "info": {
    "title": "只只HTTP 动态 API",
    "version": "1.0.0",
    "description": "仅说明现有公开动态接口合同；示例为合成数据。动态提取 兼容响应与账户白名单响应有不同封装。"
  },
  "servers": [
    {
      "url": "https://api.zzhttp.com/openapi/v1/proxy"
    }
  ],
  "security": [
    {
      "AccountAPIKey": []
    }
  ],
  "components": {
    "securitySchemes": {
      "AccountAPIKey": {
        "type": "apiKey",
        "in": "query",
        "name": "api_key"
      },
      "HeaderAPIKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAPIKey": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "paths": {
    "/whitelist/list": {
      "get": {
        "operationId": "get__whitelist_list",
        "summary": "查询动态 IP 白名单",
        "description": "仅查询本人白名单，精确 IP 过滤。",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "description": "页码，默认 1。",
            "schema": {
              "type": "integer",
              "description": "页码，默认 1。",
              "minimum": 1,
              "default": 1
            },
            "required": false
          },
          {
            "name": "page_size",
            "in": "query",
            "description": "每页条数，默认 20，最大 100。",
            "schema": {
              "type": "integer",
              "description": "每页条数，默认 20，最大 100。",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "required": false
          },
          {
            "name": "status",
            "in": "query",
            "description": "状态过滤。",
            "schema": {
              "type": "string",
              "description": "状态过滤。",
              "enum": [
                "all",
                "active",
                "disabled"
              ],
              "default": "all"
            },
            "required": false
          },
          {
            "name": "ip",
            "in": "query",
            "description": "来源 IP 精确筛选。",
            "schema": {
              "type": "string",
              "description": "来源 IP 精确筛选。"
            },
            "required": false
          }
        ],
        "x-doc-path": "/developers/api/ip-whitelist-list",
        "x-auth-notes": "使用 HTTPS；唯一非空 api_key Query，仅接受账户 API 令牌。",
        "x-response-notes": "响应不含内部字段或代理密码。提取 HTTP 200 / code 0 为成功；白名单及国家目录 code 200 为成功。POST 提取的错误使用 code/message 格式；国家目录成功响应没有 requestId。",
        "x-retry-notes": "每个令牌查询 60 次/分钟，添加或删除各 10 次/分钟。429 按 Retry-After 等待；写入结果不明先查询列表，仅重试未成功项。",
        "x-errors": [
          {
            "http": "200",
            "code": "10000",
            "description": "业务参数无效（HTTP 200 不等于业务成功）"
          },
          {
            "http": "401",
            "code": "10001",
            "description": "认证令牌无效"
          },
          {
            "http": "429",
            "code": "10000",
            "description": "请求频率超限，按 Retry-After 等待"
          }
        ],
        "responses": {
          "200": {
            "description": "成功或逐项批量结果，请同时核对业务码。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "description": "成功为 200；白名单批量任一失败为 10431。"
                    },
                    "message": {
                      "type": "string",
                      "description": "结果说明。"
                    },
                    "requestId": {
                      "type": "string",
                      "description": "请求追踪 ID。"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "description": "当前页本人白名单。",
                          "items": {
                            "type": "object",
                            "properties": {
                              "whitelist_id": {
                                "type": "integer",
                                "description": "白名单记录 ID。",
                                "minimum": 1
                              },
                              "ip": {
                                "type": "string",
                                "description": "来源 IPv4 地址，精确匹配。"
                              },
                              "remark": {
                                "type": "string",
                                "description": "客户备注，最长 255 字符。"
                              },
                              "status": {
                                "type": "integer",
                                "description": "1 启用，3 停用；已删除记录不返回。",
                                "enum": [
                                  1,
                                  3
                                ]
                              },
                              "created_at": {
                                "type": "string",
                                "description": "创建时间，RFC3339。",
                                "format": "date-time"
                              }
                            },
                            "required": [
                              "whitelist_id",
                              "ip",
                              "remark",
                              "status",
                              "created_at"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "page": {
                          "type": "integer",
                          "description": "页码，从 1 开始。"
                        },
                        "page_size": {
                          "type": "integer",
                          "description": "每页条数。"
                        },
                        "total": {
                          "type": "integer",
                          "description": "筛选后的总记录数。"
                        }
                      },
                      "required": [
                        "items",
                        "page",
                        "page_size",
                        "total"
                      ],
                      "additionalProperties": false,
                      "description": "本接口业务数据。"
                    }
                  },
                  "required": [
                    "code",
                    "message",
                    "requestId",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "examples": {
                  "success": {
                    "value": {
                      "code": 200,
                      "message": "查询成功",
                      "requestId": "demo-request-001",
                      "data": {
                        "items": [
                          {
                            "whitelist_id": 101,
                            "ip": "203.0.113.10",
                            "remark": "office",
                            "status": 1,
                            "created_at": "2026-10-06T08:00:00Z"
                          }
                        ],
                        "page": 1,
                        "page_size": 20,
                        "total": 1
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "认证错误示例；HTTP 与业务码同时检查。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "description": "数字业务错误码。"
                    },
                    "message": {
                      "type": "string",
                      "description": "错误说明。"
                    },
                    "requestId": {
                      "type": "string",
                      "description": "请求追踪 ID，非业务幂等编号。"
                    }
                  },
                  "required": [
                    "code",
                    "message",
                    "requestId"
                  ],
                  "additionalProperties": false
                },
                "examples": {
                  "error": {
                    "value": {
                      "code": 10001,
                      "message": "API令牌无效",
                      "requestId": "demo-request-001"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "cURL",
            "source": "curl --request GET \\\n  \"https://api.zzhttp.com/openapi/v1/proxy/whitelist/list?api_key=${API_KEY}\""
          }
        ]
      }
    },
    "/whitelist/add": {
      "post": {
        "operationId": "post__whitelist_add",
        "summary": "批量添加动态 IP 白名单",
        "description": "逐项白名单写入，不回滚其他已成功项。超过 100 或外层结构无效整批拒绝。示例保留 IP 仅展示结构，实际添加会拒绝文档地址。",
        "parameters": [],
        "x-doc-path": "/developers/api/ip-whitelist-add",
        "x-auth-notes": "使用 HTTPS；唯一非空 api_key Query，仅接受账户 API 令牌。",
        "x-response-notes": "响应不含内部字段或代理密码。提取 HTTP 200 / code 0 为成功；白名单及国家目录 code 200 为成功。POST 提取的错误使用 code/message 格式；国家目录成功响应没有 requestId。",
        "x-retry-notes": "每个令牌查询 60 次/分钟，添加或删除各 10 次/分钟。429 按 Retry-After 等待；写入结果不明先查询列表，仅重试未成功项。",
        "x-errors": [
          {
            "http": "200",
            "code": "10431",
            "description": "批量部分失败，检查 failed_items"
          },
          {
            "http": "401",
            "code": "10001",
            "description": "认证令牌无效"
          },
          {
            "http": "429",
            "code": "10000",
            "description": "请求频率超限，按 Retry-After 等待"
          }
        ],
        "responses": {
          "200": {
            "description": "成功或逐项批量结果，请同时核对业务码。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "description": "成功为 200；白名单批量任一失败为 10431。"
                    },
                    "message": {
                      "type": "string",
                      "description": "结果说明。"
                    },
                    "requestId": {
                      "type": "string",
                      "description": "请求追踪 ID。"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "success_count": {
                          "type": "integer",
                          "description": "成功处理条数。"
                        },
                        "failed_count": {
                          "type": "integer",
                          "description": "失败条数。"
                        },
                        "failed_items": {
                          "type": "array",
                          "description": "失败明细；成功地址不在响应中列出。",
                          "items": {
                            "type": "object",
                            "properties": {
                              "ip": {
                                "type": "string",
                                "description": "失败地址。"
                              },
                              "code": {
                                "type": "integer",
                                "description": "此项数字错误码。"
                              },
                              "reason": {
                                "type": "string",
                                "description": "失败原因。"
                              }
                            },
                            "required": [
                              "ip",
                              "code",
                              "reason"
                            ],
                            "additionalProperties": false
                          }
                        }
                      },
                      "required": [
                        "success_count",
                        "failed_count",
                        "failed_items"
                      ],
                      "additionalProperties": false,
                      "description": "本接口业务数据。"
                    }
                  },
                  "required": [
                    "code",
                    "message",
                    "requestId",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "examples": {
                  "success": {
                    "value": {
                      "code": 200,
                      "message": "处理完成",
                      "requestId": "demo-request-001",
                      "data": {
                        "success_count": 1,
                        "failed_count": 0,
                        "failed_items": []
                      }
                    }
                  },
                  "partial": {
                    "summary": "部分失败",
                    "value": {
                      "code": 10431,
                      "message": "部分失败",
                      "requestId": "demo-request-001",
                      "data": {
                        "success_count": 0,
                        "failed_count": 1,
                        "failed_items": [
                          {
                            "ip": "203.0.113.10",
                            "code": 10403,
                            "reason": "参数无效或白名单不存在"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "认证错误示例；HTTP 与业务码同时检查。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "description": "数字业务错误码。"
                    },
                    "message": {
                      "type": "string",
                      "description": "错误说明。"
                    },
                    "requestId": {
                      "type": "string",
                      "description": "请求追踪 ID，非业务幂等编号。"
                    }
                  },
                  "required": [
                    "code",
                    "message",
                    "requestId"
                  ],
                  "additionalProperties": false
                },
                "examples": {
                  "error": {
                    "value": {
                      "code": 10001,
                      "message": "API令牌无效",
                      "requestId": "demo-request-001"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "description": "每项独立处理，1–100 个海外公网 IPv4。",
                    "minItems": 1,
                    "maxItems": 100,
                    "items": {
                      "type": "object",
                      "properties": {
                        "ip": {
                          "type": "string",
                          "description": "获授权的海外公网 IPv4；IPv6、私网和保留地址拒绝。"
                        },
                        "remark": {
                          "type": "string",
                          "description": "可选备注。",
                          "maxLength": 255
                        }
                      },
                      "required": [
                        "ip"
                      ],
                      "additionalProperties": false
                    }
                  }
                },
                "required": [
                  "items"
                ],
                "additionalProperties": false
              },
              "examples": {
                "request": {
                  "summary": "请求示例",
                  "value": {
                    "items": [
                      {
                        "ip": "203.0.113.10",
                        "remark": "office"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "cURL",
            "source": "curl --request POST \\\n  \"https://api.zzhttp.com/openapi/v1/proxy/whitelist/add?api_key=${API_KEY}\" \\\n  --header 'Content-Type: application/json' \\\n  --data '{\"items\":[{\"ip\":\"203.0.113.10\",\"remark\":\"office\"}]}'"
          }
        ]
      }
    },
    "/whitelist/delete": {
      "post": {
        "operationId": "post__whitelist_delete",
        "summary": "批量删除动态 IP 白名单",
        "description": "逐项白名单写入，不回滚其他已成功项。超过 100 或外层结构无效整批拒绝。示例保留 IP 仅展示结构，实际添加会拒绝文档地址。",
        "parameters": [],
        "x-doc-path": "/developers/api/ip-whitelist-delete",
        "x-auth-notes": "使用 HTTPS；唯一非空 api_key Query，仅接受账户 API 令牌。",
        "x-response-notes": "响应不含内部字段或代理密码。提取 HTTP 200 / code 0 为成功；白名单及国家目录 code 200 为成功。POST 提取的错误使用 code/message 格式；国家目录成功响应没有 requestId。",
        "x-retry-notes": "每个令牌查询 60 次/分钟，添加或删除各 10 次/分钟。429 按 Retry-After 等待；写入结果不明先查询列表，仅重试未成功项。",
        "x-errors": [
          {
            "http": "200",
            "code": "10431",
            "description": "批量部分失败，检查 failed_items"
          },
          {
            "http": "401",
            "code": "10001",
            "description": "认证令牌无效"
          },
          {
            "http": "429",
            "code": "10000",
            "description": "请求频率超限，按 Retry-After 等待"
          }
        ],
        "responses": {
          "200": {
            "description": "成功或逐项批量结果，请同时核对业务码。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "description": "成功为 200；白名单批量任一失败为 10431。"
                    },
                    "message": {
                      "type": "string",
                      "description": "结果说明。"
                    },
                    "requestId": {
                      "type": "string",
                      "description": "请求追踪 ID。"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "success_count": {
                          "type": "integer",
                          "description": "成功处理条数。"
                        },
                        "failed_count": {
                          "type": "integer",
                          "description": "失败条数。"
                        },
                        "failed_items": {
                          "type": "array",
                          "description": "失败明细；成功地址不在响应中列出。",
                          "items": {
                            "type": "object",
                            "properties": {
                              "ip": {
                                "type": "string",
                                "description": "失败地址。"
                              },
                              "code": {
                                "type": "integer",
                                "description": "此项数字错误码。"
                              },
                              "reason": {
                                "type": "string",
                                "description": "失败原因。"
                              }
                            },
                            "required": [
                              "ip",
                              "code",
                              "reason"
                            ],
                            "additionalProperties": false
                          }
                        }
                      },
                      "required": [
                        "success_count",
                        "failed_count",
                        "failed_items"
                      ],
                      "additionalProperties": false,
                      "description": "本接口业务数据。"
                    }
                  },
                  "required": [
                    "code",
                    "message",
                    "requestId",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "examples": {
                  "success": {
                    "value": {
                      "code": 200,
                      "message": "处理完成",
                      "requestId": "demo-request-001",
                      "data": {
                        "success_count": 1,
                        "failed_count": 0,
                        "failed_items": []
                      }
                    }
                  },
                  "partial": {
                    "summary": "部分失败",
                    "value": {
                      "code": 10431,
                      "message": "部分失败",
                      "requestId": "demo-request-001",
                      "data": {
                        "success_count": 0,
                        "failed_count": 1,
                        "failed_items": [
                          {
                            "ip": "203.0.113.10",
                            "code": 10403,
                            "reason": "参数无效或白名单不存在"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "认证错误示例；HTTP 与业务码同时检查。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "description": "数字业务错误码。"
                    },
                    "message": {
                      "type": "string",
                      "description": "错误说明。"
                    },
                    "requestId": {
                      "type": "string",
                      "description": "请求追踪 ID，非业务幂等编号。"
                    }
                  },
                  "required": [
                    "code",
                    "message",
                    "requestId"
                  ],
                  "additionalProperties": false
                },
                "examples": {
                  "error": {
                    "value": {
                      "code": 10001,
                      "message": "API令牌无效",
                      "requestId": "demo-request-001"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ips": {
                    "type": "array",
                    "description": "1–100 个本人白名单 IP，不存在与他人归属统一失败。",
                    "items": {
                      "type": "string",
                      "description": "待删除的来源 IPv4。"
                    },
                    "minItems": 1,
                    "maxItems": 100
                  }
                },
                "required": [
                  "ips"
                ],
                "additionalProperties": false
              },
              "examples": {
                "request": {
                  "summary": "请求示例",
                  "value": {
                    "ips": [
                      "203.0.113.10"
                    ]
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "cURL",
            "source": "curl --request POST \\\n  \"https://api.zzhttp.com/openapi/v1/proxy/whitelist/delete?api_key=${API_KEY}\" \\\n  --header 'Content-Type: application/json' \\\n  --data '{\"ips\":[\"203.0.113.10\"]}'"
          }
        ]
      }
    },
    "/extract": {
      "get": {
        "operationId": "get__extract",
        "summary": "账户令牌 GET 提取接口",
        "description": "使用账户 API 令牌或历史 API Link 认证；实际来源 IPv4 必须在本人启用白名单，提取校验实名和协议匹配权益。GET/POST 提取为 兼容格式，不支持会话、州省和城市参数。",
        "parameters": [
          {
            "name": "num",
            "in": "query",
            "description": "提取条数。",
            "schema": {
              "type": "integer",
              "description": "提取条数。",
              "minimum": 1,
              "maximum": 100
            },
            "required": true
          },
          {
            "name": "regions",
            "in": "query",
            "description": "国家代码，来自国家目录；兼容 country 别名，同时传入须一致。",
            "schema": {
              "type": "string",
              "description": "国家代码，来自国家目录；兼容 country 别名，同时传入须一致。",
              "default": "GLOBAL"
            },
            "required": false
          },
          {
            "name": "protocol",
            "in": "query",
            "description": "HTTP 代理可 CONNECT 访问 HTTPS 目标；不接受 https。",
            "schema": {
              "type": "string",
              "description": "HTTP 代理可 CONNECT 访问 HTTPS 目标；不接受 https。",
              "enum": [
                "http",
                "socks5"
              ],
              "default": "http"
            },
            "required": false
          },
          {
            "name": "return_type",
            "in": "query",
            "description": "返回格式。",
            "schema": {
              "type": "string",
              "description": "返回格式。",
              "enum": [
                "json",
                "txt"
              ],
              "default": "json"
            },
            "required": false
          },
          {
            "name": "lb",
            "in": "query",
            "description": "TXT 分隔符：1 CRLF、2 /br、3 CR、4 LF、5 TAB、6 自定义 sb。",
            "schema": {
              "type": "string",
              "description": "TXT 分隔符：1 CRLF、2 /br、3 CR、4 LF、5 TAB、6 自定义 sb。",
              "enum": [
                "1",
                "2",
                "3",
                "4",
                "5",
                "6"
              ],
              "default": "1"
            },
            "required": false
          },
          {
            "name": "sb",
            "in": "query",
            "description": "lb=6 必填，非空且 UTF-8 字节长度最多 32。",
            "schema": {
              "type": "string",
              "description": "lb=6 必填，非空且 UTF-8 字节长度最多 32。"
            },
            "required": false
          },
          {
            "name": "request_id",
            "in": "query",
            "description": "可选幂等请求号，省略读取 X-Request-Id 或服务端生成。",
            "schema": {
              "type": "string",
              "description": "可选幂等请求号，省略读取 X-Request-Id 或服务端生成。"
            },
            "required": false
          }
        ],
        "x-doc-path": "/developers/api/api-key-extract-get",
        "x-auth-notes": "使用 HTTPS；api_key Query、X-API-Key 或 Authorization: Bearer 支持同值认证，冲突值拒绝。实际来源白名单仍须有效。",
        "x-response-notes": "响应不含内部字段或代理密码。提取 HTTP 200 / code 0 为成功；白名单及国家目录 code 200 为成功。POST 提取的错误使用 code/message 格式；国家目录成功响应没有 requestId。",
        "x-retry-notes": "请求中断复用原 requestId/request_id；部分返回通过 X-Proxy-Requested-Count、X-Proxy-Returned-Count 与 X-Proxy-Partial 判断。资源不足按 Retry-After 等待，国家目录可有限重试读取。",
        "x-errors": [
          {
            "http": "200",
            "code": "10000",
            "description": "业务参数无效（HTTP 200 不等于业务成功）"
          },
          {
            "http": "401",
            "code": "10009",
            "description": "认证令牌无效"
          },
          {
            "http": "429",
            "code": "10000",
            "description": "请求频率超限，按 Retry-After 等待"
          }
        ],
        "responses": {
          "200": {
            "description": "成功或逐项批量结果，请同时核对业务码。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "description": "兼容成功码为 0，与静态 API 成功码 200 不同。",
                      "const": 0
                    },
                    "success": {
                      "type": "boolean",
                      "description": "成功标记。",
                      "const": true
                    },
                    "msg": {
                      "type": "string",
                      "description": "结果说明。"
                    },
                    "data": {
                      "type": "array",
                      "description": "本接口业务数据。",
                      "items": {
                        "type": "object",
                        "properties": {
                          "ip": {
                            "type": "string",
                            "description": "代理网关 IP 或主机名。"
                          },
                          "port": {
                            "type": "integer",
                            "description": "代理网关端口。"
                          }
                        },
                        "required": [
                          "ip",
                          "port"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "request_ip": {
                      "type": "string",
                      "description": "服务端识别的真实调用来源 IPv4。"
                    }
                  },
                  "required": [
                    "code",
                    "success",
                    "msg",
                    "data",
                    "request_ip"
                  ],
                  "additionalProperties": false
                },
                "examples": {
                  "success": {
                    "value": {
                      "code": 0,
                      "success": true,
                      "msg": "Successfully obtained",
                      "data": [
                        {
                          "ip": "203.0.113.20",
                          "port": 7878
                        }
                      ],
                      "request_ip": "198.51.100.10"
                    }
                  }
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "example": "203.0.113.20:7878"
              }
            }
          },
          "default": {
            "description": "认证错误示例；HTTP 与业务码同时检查。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "description": "数字业务错误码。"
                    },
                    "success": {
                      "type": "boolean",
                      "description": "失败标记。",
                      "const": false
                    },
                    "msg": {
                      "type": "string",
                      "description": "错误说明。"
                    }
                  },
                  "required": [
                    "code",
                    "success",
                    "msg"
                  ],
                  "additionalProperties": false
                },
                "examples": {
                  "error": {
                    "value": {
                      "code": 10009,
                      "success": false,
                      "msg": "API令牌无效"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "cURL",
            "source": "curl --request GET \\\n  \"https://api.zzhttp.com/openapi/v1/proxy/extract?api_key=${API_KEY}&num=1&regions=GLOBAL&protocol=http\""
          }
        ],
        "security": [
          {
            "AccountAPIKey": []
          },
          {
            "HeaderAPIKey": []
          },
          {
            "BearerAPIKey": []
          }
        ],
        "x-auth-query-required": false
      },
      "post": {
        "operationId": "post__extract",
        "summary": "账户令牌 POST 提取接口",
        "description": "使用账户 API 令牌或历史 API Link 认证；实际来源 IPv4 必须在本人启用白名单，提取校验实名和协议匹配权益。GET/POST 提取为 兼容格式，不支持会话、州省和城市参数。",
        "parameters": [],
        "x-doc-path": "/developers/api/api-key-extract-post",
        "x-auth-notes": "使用 HTTPS；api_key Query、X-API-Key 或 Authorization: Bearer 支持同值认证，冲突值拒绝。实际来源白名单仍须有效。",
        "x-response-notes": "响应不含内部字段或代理密码。提取 HTTP 200 / code 0 为成功；白名单及国家目录 code 200 为成功。POST 提取的错误使用 code/message 格式；国家目录成功响应没有 requestId。",
        "x-retry-notes": "请求中断复用原 requestId/request_id；部分返回通过 X-Proxy-Requested-Count、X-Proxy-Returned-Count 与 X-Proxy-Partial 判断。资源不足按 Retry-After 等待，国家目录可有限重试读取。",
        "x-errors": [
          {
            "http": "200",
            "code": "10000",
            "description": "业务参数无效（HTTP 200 不等于业务成功）"
          },
          {
            "http": "401",
            "code": "10009",
            "description": "认证令牌无效"
          },
          {
            "http": "429",
            "code": "10000",
            "description": "请求频率超限，按 Retry-After 等待"
          }
        ],
        "responses": {
          "200": {
            "description": "成功或逐项批量结果，请同时核对业务码。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "description": "兼容成功码为 0，与静态 API 成功码 200 不同。",
                      "const": 0
                    },
                    "success": {
                      "type": "boolean",
                      "description": "成功标记。",
                      "const": true
                    },
                    "msg": {
                      "type": "string",
                      "description": "结果说明。"
                    },
                    "data": {
                      "type": "array",
                      "description": "本接口业务数据。",
                      "items": {
                        "type": "object",
                        "properties": {
                          "ip": {
                            "type": "string",
                            "description": "代理网关 IP 或主机名。"
                          },
                          "port": {
                            "type": "integer",
                            "description": "代理网关端口。"
                          }
                        },
                        "required": [
                          "ip",
                          "port"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "request_ip": {
                      "type": "string",
                      "description": "服务端识别的真实调用来源 IPv4。"
                    }
                  },
                  "required": [
                    "code",
                    "success",
                    "msg",
                    "data",
                    "request_ip"
                  ],
                  "additionalProperties": false
                },
                "examples": {
                  "success": {
                    "value": {
                      "code": 0,
                      "success": true,
                      "msg": "Successfully obtained",
                      "data": [
                        {
                          "ip": "203.0.113.20",
                          "port": 7878
                        }
                      ],
                      "request_ip": "198.51.100.10"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "认证错误示例；HTTP 与业务码同时检查。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "description": "数字业务错误码。"
                    },
                    "message": {
                      "type": "string",
                      "description": "错误说明。"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": false
                },
                "examples": {
                  "error": {
                    "value": {
                      "code": 10009,
                      "message": "API令牌无效"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "requestId": {
                    "type": "string",
                    "description": "可选业务请求号；网络中断后使用同号重试。"
                  },
                  "entitlementId": {
                    "type": "integer",
                    "description": "可选本人权益 ID，省略由服务端选择。"
                  },
                  "whitelistId": {
                    "type": "integer",
                    "description": "可选本人白名单 ID；实际来源仍需一致。"
                  },
                  "quantity": {
                    "type": "integer",
                    "description": "请求条数，1–100。",
                    "minimum": 1,
                    "maximum": 100
                  },
                  "protocol": {
                    "type": "string",
                    "description": "代理协议。",
                    "enum": [
                      "HTTP",
                      "HTTPS",
                      "SOCKS5"
                    ]
                  },
                  "country": {
                    "type": "string",
                    "description": "国家代码，省略按全球处理。",
                    "default": "GLOBAL"
                  },
                  "agreementConfirmed": {
                    "type": "boolean",
                    "description": "必须确认使用协议。",
                    "const": true
                  }
                },
                "required": [
                  "quantity",
                  "protocol",
                  "agreementConfirmed"
                ],
                "additionalProperties": false
              },
              "examples": {
                "request": {
                  "summary": "请求示例",
                  "value": {
                    "requestId": "extract-demo-001",
                    "quantity": 1,
                    "protocol": "HTTP",
                    "country": "GLOBAL",
                    "agreementConfirmed": true
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "cURL",
            "source": "curl --request POST \\\n  \"https://api.zzhttp.com/openapi/v1/proxy/extract?api_key=${API_KEY}\" \\\n  --header 'Content-Type: application/json' \\\n  --data '{\"requestId\":\"extract-demo-001\",\"quantity\":1,\"protocol\":\"HTTP\",\"country\":\"GLOBAL\",\"agreementConfirmed\":true}'"
          }
        ],
        "security": [
          {
            "AccountAPIKey": []
          },
          {
            "HeaderAPIKey": []
          },
          {
            "BearerAPIKey": []
          }
        ],
        "x-auth-query-required": false
      }
    },
    "/countries": {
      "get": {
        "operationId": "get__countries",
        "summary": "查询动态 API 国家目录",
        "description": "查询动态 API 国家目录及当前可用稳定端口数量；令牌鉴权不代表提取已满足来源白名单和权益条件。",
        "parameters": [],
        "x-doc-path": "/developers/api/api-countries",
        "x-auth-notes": "使用 HTTPS；api_key Query、X-API-Key 或 Authorization: Bearer 支持同值认证，冲突值拒绝。实际来源白名单仍须有效。",
        "x-response-notes": "响应不含内部字段或代理密码。提取 HTTP 200 / code 0 为成功；白名单及国家目录 code 200 为成功。POST 提取的错误使用 code/message 格式；国家目录成功响应没有 requestId。",
        "x-retry-notes": "国家目录读取遇到临时错误可有限重试，429 按 Retry-After 等待。",
        "x-errors": [
          {
            "http": "200",
            "code": "10000",
            "description": "业务参数无效（HTTP 200 不等于业务成功）"
          },
          {
            "http": "401",
            "code": "10009",
            "description": "认证令牌无效"
          },
          {
            "http": "429",
            "code": "10000",
            "description": "请求频率超限，按 Retry-After 等待"
          }
        ],
        "responses": {
          "200": {
            "description": "成功或逐项批量结果，请同时核对业务码。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "description": "成功为 200；白名单批量任一失败为 10431。"
                    },
                    "message": {
                      "type": "string",
                      "description": "结果说明。"
                    },
                    "data": {
                      "type": "array",
                      "description": "本接口业务数据。",
                      "items": {
                        "type": "object",
                        "properties": {
                          "countryRouteId": {
                            "type": "integer",
                            "description": "公开国家路由 ID。"
                          },
                          "countryCode": {
                            "type": "string",
                            "description": "国家代码，取此返回值用于地区提取；GLOBAL 表示全球。"
                          },
                          "countryName": {
                            "type": "string",
                            "description": "国家展示名称。"
                          },
                          "availableCount": {
                            "type": "integer",
                            "description": "当前可用稳定端口数量，不是代理出口库存。"
                          }
                        },
                        "required": [
                          "countryRouteId",
                          "countryCode",
                          "countryName",
                          "availableCount"
                        ],
                        "additionalProperties": false
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message",
                    "data"
                  ],
                  "additionalProperties": false
                },
                "examples": {
                  "success": {
                    "value": {
                      "code": 200,
                      "message": "查询成功",
                      "data": [
                        {
                          "countryRouteId": 1,
                          "countryCode": "USA",
                          "countryName": "美国",
                          "availableCount": 20
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "认证错误示例；HTTP 与业务码同时检查。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "description": "数字业务错误码。"
                    },
                    "success": {
                      "type": "boolean",
                      "description": "失败标记。",
                      "const": false
                    },
                    "msg": {
                      "type": "string",
                      "description": "错误说明。"
                    }
                  },
                  "required": [
                    "code",
                    "success",
                    "msg"
                  ],
                  "additionalProperties": false
                },
                "examples": {
                  "error": {
                    "value": {
                      "code": 10009,
                      "success": false,
                      "msg": "API令牌无效"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "cURL",
            "source": "curl --request GET \\\n  \"https://api.zzhttp.com/openapi/v1/proxy/countries?api_key=${API_KEY}\""
          }
        ],
        "security": [
          {
            "AccountAPIKey": []
          },
          {
            "HeaderAPIKey": []
          },
          {
            "BearerAPIKey": []
          }
        ],
        "x-auth-query-required": false
      }
    }
  }
}