{ "openapi": "3.0.3", "info": { "title": "700SU 静态住宅 IP 客户 API", "version": "2026-11-04", "description": "基于2026-11-04线上现有客户接口整理。范围：新静态住宅IP，账户余额购买与续费。使用登录Token鉴权；不是独立API Key接口。示例为虚构字段示意。创建订单不支持客户端幂等键；写请求超时先查单，禁止盲目重发。当前无客户交付回调，请轮询原订单。" }, "servers": [ { "url": "https://700su.com" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "账户" }, { "name": "资源" }, { "name": "购买" }, { "name": "续费" } ], "paths": { "/api/auth/login": { "post": { "tags": [ "账户" ], "summary": "登录并获取 Token", "description": "使用700SU客户账号邮箱和密码登录。成功后保存token，后续以Authorization: Bearer传入。Token最长有效期7天，退出登录、账号停用等会使会话提前失效；没有refresh_token接口。", "operationId": "operation_01", "responses": { "200": { "description": "成功；字段示例为节选，未列出的字段不应作为业务依赖。", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "会话Token，禁止公开或写入日志" }, "user": { "type": "object", "properties": { "id": { "type": "integer", "description": "" }, "email": { "type": "string", "description": "" }, "status": { "type": "string", "description": "" }, "balance_cny": { "type": "number", "description": "" } } } } }, "example": { "token": "YOUR_ACCESS_TOKEN", "user": { "id": 100, "email": "your-account@example.com", "status": "active", "balance_cny": 100 } } } } }, "401": { "description": "未登录或会话失效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "无权访问", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求过于频繁", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "处理异常，写请求结果可能不确定", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "客户账号邮箱" }, "password": { "type": "string", "description": "账号密码", "format": "password" } }, "required": [ "email", "password" ] }, "example": { "email": "your-account@example.com", "password": "YOUR_ACCOUNT_PASSWORD" } } } } } }, "/api/users/me": { "get": { "tags": [ "账户" ], "summary": "查询账户和余额", "description": "读取balance_cny获取余额。discount_rate只是普通折扣规则；最终支付价以订单amount_cny或续费total_cny为准。", "operationId": "operation_02", "responses": { "200": { "description": "成功；字段示例为节选，未列出的字段不应作为业务依赖。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" }, "example": { "id": 100, "email": "your-account@example.com", "status": "active", "balance_cny": 100, "discount_rate": 1 } } } }, "401": { "description": "未登录或会话失效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "无权访问", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "处理异常，写请求结果可能不确定", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/logout": { "post": { "tags": [ "账户" ], "summary": "注销当前 Token", "description": "注销当前会话后需要重新登录。", "operationId": "operation_03", "responses": { "200": { "description": "成功；字段示例为节选，未列出的字段不应作为业务依赖。", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "" } } }, "example": { "ok": true } } } }, "401": { "description": "未登录或会话失效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "处理异常，写请求结果可能不确定", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/public/catalog": { "get": { "tags": [ "资源" ], "summary": "查询公开地区与线路", "description": "公开可售静态目录。按country、city、line、ip_type四个原值选择商品；不要把展示标签或国家缩写作为下单参数。ip_kind用于区分原生与广播，不能替代ip_type。库存仅供参考，不预留资源。", "operationId": "operation_04", "responses": { "200": { "description": "成功；字段示例为节选，未列出的字段不应作为业务依赖。", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogItem" } }, "example": [ { "country": "美国", "city": "示例城市", "line": "原生 IP · 示例线路", "ip_type": "static_residential", "ip_kind": "native", "available_count": 100, "price_30d": 25 } ] } } }, "500": { "description": "处理异常，写请求结果可能不确定", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "服务暂不可用，先核对原单状态", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/api/inventory/availability": { "get": { "tags": [ "资源" ], "summary": "查询账号可见价格", "description": "登录后查询。若customer_pricing为unavailable，停止自动购买；customer_price_30d存在且为正数时即为专属单价，不再乘折扣。无专属价时可用price_30d×discount_rate做预估，最终以创建订单的amount_cny为准。只依赖本文列出的业务字段，其余字段忽略。", "operationId": "operation_05", "responses": { "200": { "description": "成功；字段示例为节选，未列出的字段不应作为业务依赖。", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerCatalogItem" } }, "example": [ { "country": "美国", "city": "示例城市", "line": "原生 IP · 示例线路", "ip_type": "static_residential", "price_30d": 25, "customer_price_30d": 10, "customer_pricing": "custom", "available_count": 100 } ] } } }, "401": { "description": "未登录或会话失效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "无权访问", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "处理异常，写请求结果可能不确定", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/static/available-cidrs": { "get": { "tags": [ "资源" ], "summary": "查询可选 IP 号段", "description": "传入选中线路的四个原值。items为空表示当前没有可选号段；随机分配时创建订单不传selected_cidr_id。指定号段只能选择CIDR范围，不能指定完整IP。号段结果缓存约60秒；下单时重新校验。此接口当前按来源IP每分钟最多90次。", "operationId": "operation_06", "responses": { "200": { "description": "成功；字段示例为节选，未列出的字段不应作为业务依赖。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CIDRs" }, "example": { "supported": true, "items": [ { "id": "OPAQUE_CIDR_ID", "cidr": "192.0.2.0/24", "available_count": 12 } ] } } } }, "400": { "description": "参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求过于频繁", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "服务暂不可用，先核对原单状态", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "description": "目录返回的国家／地区原值" } }, { "name": "city", "in": "query", "required": true, "schema": { "type": "string", "description": "目录返回的城市原值" } }, { "name": "line", "in": "query", "required": true, "schema": { "type": "string", "description": "目录返回的完整线路原值，不可自行拼接" } }, { "name": "ip_type", "in": "query", "required": true, "schema": { "type": "string", "description": "按目录原值传入；静态住宅通常为 static_residential" } } ], "security": [] } }, "/api/orders": { "post": { "tags": [ "购买" ], "summary": "创建购买订单", "description": "仅创建待支付订单，不扣余额、不代表预留库存。保存id、order_no与amount_cny。未付款报价保留30分钟，过期后重新确认价格。当前不接受客户端幂等键；相同请求再次提交会创建另一笔订单，超时后不可直接重发。", "operationId": "operation_07", "responses": { "201": { "description": "成功；字段示例为节选，未列出的字段不应作为业务依赖。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "example": { "id": 12345, "order_no": "AU-20261104000000-DEMO", "country": "美国", "city": "示例城市", "line": "原生 IP · 示例线路", "ip_type": "static_residential", "quantity": 1, "cycle_days": 30, "protocol": "socks5", "amount_cny": 25, "payment_status": "pending", "order_status": "pending" } } } }, "400": { "description": "参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "未登录或会话失效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "无权访问", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务状态不允许继续", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "处理异常，写请求结果可能不确定", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "服务暂不可用，先核对原单状态", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "type": "string", "description": "目录返回的国家／地区原值" }, "city": { "type": "string", "description": "目录返回的城市原值" }, "line": { "type": "string", "description": "目录返回的完整线路原值，不可自行拼接" }, "ip_type": { "type": "string", "description": "按目录原值传入；静态住宅通常为 static_residential" }, "quantity": { "type": "integer", "description": "购买数量，1–500", "minimum": 1, "maximum": 500, "default": 1 }, "cycle_days": { "type": "integer", "description": "当前只支持30天", "enum": [ 30 ], "default": 30 }, "protocol": { "type": "string", "description": "明确传入http或socks5；默认http", "enum": [ "http", "socks5" ], "default": "http" }, "selected_cidr_id": { "type": "string", "description": "可选。号段接口返回的id，原样传入；随机分配时省略", "maxLength": 100 } }, "required": [ "country", "city", "line", "ip_type" ] }, "example": { "country": "从目录复制国家", "city": "从目录复制城市", "line": "从目录复制完整线路", "ip_type": "static_residential", "quantity": 1, "cycle_days": 30, "protocol": "socks5" } } } } } }, "/api/orders/{orderNo}": { "get": { "tags": [ "购买" ], "summary": "按订单号查询", "description": "orderNo使用AU-开头的订单号。以payment_status判断是否付款，以order_status判断交付；delivery_review_required=true时记录原订单号并联系客服。", "operationId": "operation_08", "responses": { "200": { "description": "成功；字段示例为节选，未列出的字段不应作为业务依赖。", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/Order" }, "payment": { "type": "object", "properties": {}, "nullable": true } } }, "example": { "order": { "id": 12345, "order_no": "AU-20261104000000-DEMO", "country": "美国", "city": "示例城市", "line": "原生 IP · 示例线路", "ip_type": "static_residential", "quantity": 1, "cycle_days": 30, "protocol": "socks5", "amount_cny": 25, "payment_status": "paid", "order_status": "provisioning", "delivery_review_required": false, "quote_expired": false, "quote_expires_at": "2026-11-04T00:30:00Z" }, "payment": null } } } }, "401": { "description": "未登录或会话失效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "无权访问", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "处理异常，写请求结果可能不确定", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "orderNo", "in": "path", "required": true, "schema": { "type": "string", "description": "" } } ] } }, "/api/orders/id/{orderId}": { "get": { "tags": [ "购买" ], "summary": "按内部 ID 查询订单", "description": "orderId使用创建订单返回的整数id；与业务订单号不同。字段和按订单号查询一致。", "operationId": "operation_09", "responses": { "200": { "description": "成功；字段示例为节选，未列出的字段不应作为业务依赖。", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/Order" }, "payment": { "type": "object", "properties": {}, "nullable": true } } } } } }, "400": { "description": "参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "未登录或会话失效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "无权访问", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "处理异常，写请求结果可能不确定", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "integer", "description": "", "minimum": 1 } } ] } }, "/api/users/me/orders": { "get": { "tags": [ "购买" ], "summary": "查询本人购买订单", "description": "当前返回本人购买订单数组，按内部id倒序，不支持分页。可用于创建请求超时后核对订单。列表可能包含历史产品，接入程序应只处理本次接入创建或明确选定的订单，不要自动支付全部待付订单。同规格订单无法唯一匹配时交人工核对。", "operationId": "operation_10", "responses": { "200": { "description": "成功；字段示例为节选，未列出的字段不应作为业务依赖。", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "example": [ { "id": 12345, "order_no": "AU-20261104000000-DEMO", "country": "美国", "city": "示例城市", "line": "原生 IP · 示例线路", "ip_type": "static_residential", "quantity": 1, "cycle_days": 30, "protocol": "socks5", "amount_cny": 25, "payment_status": "pending", "order_status": "pending" } ] } } }, "401": { "description": "未登录或会话失效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "无权访问", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "处理异常，写请求结果可能不确定", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/orders/{orderNo}/pay-balance": { "post": { "tags": [ "购买" ], "summary": "用余额支付购买订单", "description": "真实扣款操作。无业务请求体；调用前查单并核对amount_cny与预算。200且ok=true表示请求已处理，不代表IP已交付。already=true表示这笔订单此前已支付；继续查询该订单，不另建单。网络超时或5xx后先查原订单。", "operationId": "operation_11", "responses": { "200": { "description": "成功；字段示例为节选，未列出的字段不应作为业务依赖。", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "" }, "already": { "type": "boolean", "description": "" }, "order": { "$ref": "#/components/schemas/Order" }, "assigned": { "type": "array", "items": { "$ref": "#/components/schemas/IP" } }, "balance_before": { "type": "number", "description": "" }, "balance_after": { "type": "number", "description": "" } } }, "example": { "ok": true, "already": false, "order": { "id": 12345, "order_no": "AU-20261104000000-DEMO", "country": "美国", "city": "示例城市", "line": "原生 IP · 示例线路", "ip_type": "static_residential", "quantity": 1, "cycle_days": 30, "protocol": "socks5", "amount_cny": 25, "payment_status": "paid", "order_status": "provisioning", "payment_network": "BALANCE" }, "assigned": [], "balance_before": 100, "balance_after": 75 } } } }, "401": { "description": "未登录或会话失效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "无权访问", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务状态不允许继续", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "处理异常，写请求结果可能不确定", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "服务暂不可用，先核对原单状态", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "orderNo", "in": "path", "required": true, "schema": { "type": "string", "description": "" } } ] } }, "/api/orders/id/{orderId}/ips": { "get": { "tags": [ "购买" ], "summary": "提取该订单交付的 IP", "description": "使用内部id查询。响应为对象，IP数组位于ips。连接地址优先使用connection_host，否则使用ip，再配合port、username、password。协议采用订单protocol。已付款时ips可能暂时为空，应等待原订单完成。只把fulfilled且数量匹配的结果当作完整交付。", "operationId": "operation_12", "responses": { "200": { "description": "成功；字段示例为节选，未列出的字段不应作为业务依赖。", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/Order" }, "payment": { "type": "object", "properties": {}, "nullable": true }, "ips": { "type": "array", "items": { "$ref": "#/components/schemas/IP" } } } }, "example": { "order": { "id": 12345, "order_no": "AU-20261104000000-DEMO", "country": "美国", "city": "示例城市", "line": "原生 IP · 示例线路", "ip_type": "static_residential", "quantity": 1, "cycle_days": 30, "protocol": "socks5", "amount_cny": 25, "payment_status": "paid", "order_status": "fulfilled" }, "payment": null, "ips": [ { "id": 67890, "ip": "192.0.2.10", "connection_host": null, "port": 10001, "username": "EXAMPLE_USER", "password": "EXAMPLE_PASSWORD", "expires_at": "2026-12-04T00:00:00Z" } ] } } } }, "400": { "description": "参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "未登录或会话失效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "无权访问", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "处理异常，写请求结果可能不确定", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "integer", "description": "", "minimum": 1 } } ] } }, "/api/orders/{orderNo}/cancel": { "post": { "tags": [ "购买" ], "summary": "取消未付款购买订单", "description": "仅用于未付款订单。已经支付或正在交付的订单不可通过此接口取消；不要在付款状态不明时盲目取消。", "operationId": "operation_13", "responses": { "200": { "description": "成功；字段示例为节选，未列出的字段不应作为业务依赖。", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "" }, "already": { "type": "boolean", "description": "" }, "order_no": { "type": "string", "description": "" }, "order_status": { "type": "string", "description": "" } } }, "example": { "ok": true, "order_no": "AU-20261104000000-DEMO", "order_status": "cancelled" } } } }, "401": { "description": "未登录或会话失效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "无权访问", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务状态不允许继续", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "处理异常，写请求结果可能不确定", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "orderNo", "in": "path", "required": true, "schema": { "type": "string", "description": "" } } ] } }, "/api/ip-renewals/identify": { "post": { "tags": [ "续费" ], "summary": "识别 IP 与续费价格", "description": "使用已交付IP的信息识别，建议同时提供用户名和密码以避免同入口多账号歧义。renew_supported=true仅表示支持续费，仍需确认未到期；renewal_prices.price_30d为该账号续费单价，最终以创建批次的total_cny为准。", "operationId": "operation_14", "responses": { "200": { "description": "成功；字段示例为节选，未列出的字段不应作为业务依赖。", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "" }, "match_mode": { "type": "string", "description": "" }, "ip": { "$ref": "#/components/schemas/IP" }, "renew_supported": { "type": "boolean", "description": "" }, "renewal": { "type": "object", "properties": { "configured": { "type": "boolean", "description": "" }, "renew_supported": { "type": "boolean", "description": "" } } }, "renewal_prices": { "type": "object", "properties": { "price_30d": { "type": "number", "description": "" } }, "nullable": true } } }, "example": { "ok": true, "ip": { "id": 67890, "ip": "192.0.2.10", "connection_host": null, "port": 10001, "username": "EXAMPLE_USER", "password": "EXAMPLE_PASSWORD", "expires_at": "2026-12-04T00:00:00Z" }, "renew_supported": true, "renewal_prices": { "price_30d": 25 } } } } }, "400": { "description": "参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "未登录或会话失效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "无权访问", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务状态不允许继续", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "处理异常，写请求结果可能不确定", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "string", "description": "IP或连接入口" }, "port": { "type": "integer", "description": "端口", "minimum": 1, "maximum": 65535 }, "username": { "type": "string", "description": "建议传入；与password成对出现" }, "password": { "type": "string", "description": "代理密码，与username成对出现", "format": "password" } }, "required": [ "ip", "port" ] }, "example": { "ip": "192.0.2.10", "port": 10001, "username": "EXAMPLE_USER", "password": "EXAMPLE_PASSWORD" } } } } } }, "/api/ip-renewals/orders": { "post": { "tags": [ "续费" ], "summary": "创建续费批次", "description": "ip_ids使用交付接口返回的实例id，不是IP地址或购买订单id。一次1–500个，当前仅30天。只有本人名下可续费且未到期的实例可创建。不扣余额。返回renewal_order_exists时使用错误内batch_no查询原批次，不能重复创建。", "operationId": "operation_15", "responses": { "201": { "description": "成功；字段示例为节选，未列出的字段不应作为业务依赖。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenewalBatch" }, "example": { "ok": true, "batch_no": "RN-EXAMPLE-0001", "cycle_days": 30, "item_count": 1, "total_cny": 25, "payment_status": "pending", "renewal_status": "draft", "items": [ { "ip_id": 67890, "amount_cny": 25, "old_expires_at": "2026-12-04T00:00:00Z" } ] } } } }, "400": { "description": "参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "未登录或会话失效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "无权访问", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务状态不允许继续", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "处理异常，写请求结果可能不确定", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "服务暂不可用，先核对原单状态", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ip_ids": { "type": "array", "items": { "type": "integer", "description": "IP实例ID", "minimum": 1 }, "description": "本账号已交付且未到期的IP实例ID数组", "minItems": 1, "maxItems": 500 }, "cycle_days": { "type": "integer", "description": "固定30", "enum": [ 30 ] } }, "required": [ "ip_ids", "cycle_days" ] }, "example": { "ip_ids": [ 67890 ], "cycle_days": 30 } } } } } }, "/api/ip-renewals/orders/{batchNo}": { "get": { "tags": [ "续费" ], "summary": "查询续费批次", "description": "付款前检查can_pay、payment_block_reason、total_cny。付款后检查renewal_status及每个items明细的新到期时间；payment_status=paid不是续费成功的充分条件。", "operationId": "operation_16", "responses": { "200": { "description": "成功；字段示例为节选，未列出的字段不应作为业务依赖。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenewalBatch" }, "example": { "batch_no": "RN-EXAMPLE-0001", "item_count": 1, "total_cny": 25, "can_pay": true, "payment_block_reason": null, "payment_status": "pending", "renewal_status": "draft", "items": [ { "ip_id": 67890, "old_expires_at": "2026-12-04T00:00:00Z", "new_expires_at": null } ] } } } }, "401": { "description": "未登录或会话失效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "无权访问", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "处理异常，写请求结果可能不确定", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "batchNo", "in": "path", "required": true, "schema": { "type": "string", "description": "" } } ] } }, "/api/users/me/renewal-orders": { "get": { "tags": [ "续费" ], "summary": "查询本人续费批次列表", "description": "按最新批次倒序返回，无分页。列表中的合计金额字段为amount_cny；详情／创建响应使用total_cny。用于查找原批次，避免重复创建。只处理已选定的本次接入资源对应批次。", "operationId": "operation_17", "responses": { "200": { "description": "成功；字段示例为节选，未列出的字段不应作为业务依赖。", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "batch_no": { "type": "string", "description": "" }, "amount_cny": { "type": "number", "description": "批次合计" }, "item_count": { "type": "integer", "description": "" }, "cycle_days": { "type": "integer", "description": "" }, "payment_status": { "type": "string", "description": "" }, "renewal_status": { "type": "string", "description": "" }, "created_at": { "type": "string", "description": "" } } } }, "example": [ { "batch_no": "RN-EXAMPLE-0001", "amount_cny": 25, "item_count": 1, "cycle_days": 30, "payment_status": "pending", "renewal_status": "draft" } ] } } }, "401": { "description": "未登录或会话失效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "无权访问", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "处理异常，写请求结果可能不确定", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/ip-renewals/orders/{batchNo}/pay-balance": { "post": { "tags": [ "续费" ], "summary": "用余额支付续费", "description": "真实扣款操作。200或202均须读取响应中的状态：202表示已付款但仍在处理或需要核查，不能再次创建续费批次来补做。已有paid状态时继续查询；仅全部completed且到期时间已延长才算完成。", "operationId": "operation_18", "responses": { "200": { "description": "成功；字段示例为节选，未列出的字段不应作为业务依赖。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenewalBatch" }, "example": { "ok": true, "already": false, "batch_no": "RN-EXAMPLE-0001", "payment_status": "paid", "renewal_status": "processing", "item_count": 1, "total_cny": 25 } } } }, "202": { "description": "已支付，处理未完成或需要核查。继续查询原批次，不再付款。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenewalBatch" } } } }, "401": { "description": "未登录或会话失效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "无权访问", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务状态不允许继续", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "处理异常，写请求结果可能不确定", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "服务暂不可用，先核对原单状态", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "batchNo", "in": "path", "required": true, "schema": { "type": "string", "description": "" } } ] } }, "/api/ip-renewals/orders/{batchNo}/cancel": { "post": { "tags": [ "续费" ], "summary": "取消未付款续费批次", "description": "只能取消全部未付款且均为draft的批次。已支付或进入处理状态的批次不可取消。", "operationId": "operation_19", "responses": { "200": { "description": "成功；字段示例为节选，未列出的字段不应作为业务依赖。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenewalBatch" }, "example": { "ok": true, "batch_no": "RN-EXAMPLE-0001", "payment_status": "pending", "renewal_status": "cancelled", "item_count": 1 } } } }, "400": { "description": "参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "未登录或会话失效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "无权访问", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务状态不允许继续", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "处理异常，写请求结果可能不确定", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "batchNo", "in": "path", "required": true, "schema": { "type": "string", "description": "" } } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "由POST /api/auth/login返回，最长7天；勿使用代理账号密码代替。" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "机器错误代码" }, "message": { "type": "string", "description": "可选提示" } }, "required": [ "error" ] }, "Account": { "type": "object", "properties": { "id": { "type": "integer", "description": "" }, "email": { "type": "string", "description": "" }, "status": { "type": "string", "description": "" }, "balance_cny": { "type": "number", "description": "人民币账户余额" }, "discount_rate": { "type": "number", "description": "普通折扣乘数，例如0.4表示4折；专属价可能覆盖此规则" }, "active_ips": { "type": "integer", "description": "有效IP数量" }, "orders_count": { "type": "integer", "description": "本月购买订单数量" }, "total_spend_cny": { "type": "number", "description": "累计已支付购买订单金额" } } }, "CatalogItem": { "type": "object", "properties": { "country": { "type": "string", "description": "目录返回的国家／地区原值" }, "city": { "type": "string", "description": "目录返回的城市原值" }, "line": { "type": "string", "description": "目录返回的完整线路原值，不可自行拼接" }, "ip_type": { "type": "string", "description": "按目录原值传入；静态住宅通常为 static_residential" }, "continent": { "type": "string", "description": "洲／大区" }, "ip_kind": { "type": "string", "description": "native：原生；broadcast：广播" }, "ip_kind_label": { "type": "string", "description": "类型显示名" }, "country_code": { "type": "string", "description": "国家代码，以返回值为准", "nullable": true }, "available_count": { "type": "integer", "description": "可售库存参考值；创建及支付时会再次检查", "minimum": 0 }, "price_30d": { "type": "number", "description": "公开30天单价，人民币", "nullable": true } } }, "CustomerCatalogItem": { "type": "object", "properties": { "country": { "type": "string", "description": "目录返回的国家／地区原值" }, "city": { "type": "string", "description": "目录返回的城市原值" }, "line": { "type": "string", "description": "目录返回的完整线路原值，不可自行拼接" }, "ip_type": { "type": "string", "description": "按目录原值传入；静态住宅通常为 static_residential" }, "continent": { "type": "string", "description": "洲／大区" }, "ip_kind": { "type": "string", "description": "native：原生；broadcast：广播" }, "ip_kind_label": { "type": "string", "description": "类型显示名" }, "country_code": { "type": "string", "description": "国家代码，以返回值为准", "nullable": true }, "available_count": { "type": "integer", "description": "可售库存参考值；创建及支付时会再次检查", "minimum": 0 }, "price_30d": { "type": "number", "description": "公开30天单价，人民币", "nullable": true }, "customer_price_30d": { "type": "number", "description": "出现时为当前账号专属30天单价，不再重复打折", "nullable": true }, "customer_pricing": { "type": "string", "description": "custom：专属价；unavailable：价格暂不可用；字段也可能省略" } } }, "Order": { "type": "object", "properties": { "id": { "type": "integer", "description": "700SU内部订单ID；提取IP使用此ID" }, "order_no": { "type": "string", "description": "AU-开头的业务订单号；支付及查单使用此值" }, "country": { "type": "string", "description": "目录返回的国家／地区原值" }, "city": { "type": "string", "description": "目录返回的城市原值" }, "line": { "type": "string", "description": "目录返回的完整线路原值，不可自行拼接" }, "ip_type": { "type": "string", "description": "按目录原值传入；静态住宅通常为 static_residential" }, "quantity": { "type": "integer", "description": "购买数量" }, "cycle_days": { "type": "integer", "description": "30天" }, "protocol": { "type": "string", "description": "http 或 socks5" }, "amount_cny": { "type": "number", "description": "本订单最终应付人民币总额，已包含账号价格规则" }, "payment_status": { "type": "string", "description": "pending 或 paid；未知值不得视为成功" }, "order_status": { "type": "string", "description": "pending、provisioning、fulfilled、cancelled 等；以返回为准" }, "payment_network": { "type": "string", "description": "余额支付后为 BALANCE", "nullable": true }, "ip_prefix": { "type": "string", "description": "所选号段", "nullable": true }, "created_at": { "type": "string", "description": "订单创建时间" }, "paid_at": { "type": "string", "description": "支付时间", "nullable": true }, "delivery_review_required": { "type": "boolean", "description": "仅详情／列表等部分响应提供。true时停止自动重下单并联系客服" }, "quote_expired": { "type": "boolean", "description": "详情提供；未付订单报价是否已过期" }, "quote_expires_at": { "type": "string", "description": "详情提供；ISO 8601报价截止时间", "nullable": true } } }, "IP": { "type": "object", "properties": { "id": { "type": "integer", "description": "700SU的IP实例ID，用于续费" }, "ip": { "type": "string", "description": "IP地址" }, "connection_host": { "type": "string", "description": "连接入口；非空时优先使用，否则使用ip", "nullable": true }, "port": { "type": "integer", "description": "代理端口" }, "username": { "type": "string", "description": "代理用户名，敏感信息" }, "password": { "type": "string", "description": "代理密码，敏感信息" }, "country": { "type": "string", "description": "目录返回的国家／地区原值" }, "city": { "type": "string", "description": "目录返回的城市原值" }, "line": { "type": "string", "description": "目录返回的完整线路原值，不可自行拼接" }, "ip_type": { "type": "string", "description": "按目录原值传入；静态住宅通常为 static_residential" }, "ip_prefix": { "type": "string", "description": "已选CIDR号段；随机分配可能为空", "nullable": true }, "status": { "type": "string", "description": "assigned 表示已分配；仍需核对到期时间" }, "expires_at": { "type": "string", "description": "实际到期时间", "nullable": true } } }, "RenewalItem": { "type": "object", "properties": { "id": { "type": "integer", "description": "续费明细ID" }, "ip_id": { "type": "integer", "description": "IP实例ID" }, "renewal_no": { "type": "string", "description": "续费明细号" }, "batch_no": { "type": "string", "description": "续费批次号" }, "amount_cny": { "type": "number", "description": "该IP续费最终价格" }, "cycle_days": { "type": "integer", "description": "30天" }, "payment_status": { "type": "string", "description": "" }, "renewal_status": { "type": "string", "description": "" }, "old_expires_at": { "type": "string", "description": "续费前到期时间", "nullable": true }, "new_expires_at": { "type": "string", "description": "确认延长后的到期时间，完成前可能为空", "nullable": true }, "current_expires_at": { "type": "string", "description": "当前到期时间，查询详情时提供", "nullable": true } } }, "RenewalBatch": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "" }, "batch_no": { "type": "string", "description": "RN-开头的续费批次号" }, "cycle_days": { "type": "integer", "description": "" }, "item_count": { "type": "integer", "description": "" }, "total_cny": { "type": "number", "description": "本批最终应付总额" }, "payment_status": { "type": "string", "description": "pending 或 paid" }, "renewal_status": { "type": "string", "description": "draft、processing、renewed_pending_sync、retry_required、completed、cancelled、failed_confirmed、refunded、partially_completed、partially_resolved" }, "can_pay": { "type": "boolean", "description": "查询详情时提供，付款前检查" }, "payment_block_reason": { "type": "string", "description": "查询详情时提供；阻止付款的错误代码", "nullable": true }, "already": { "type": "boolean", "description": "重复付款请求可能返回" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/RenewalItem" } } } }, "CIDRs": { "type": "object", "properties": { "supported": { "type": "boolean", "description": "是否有可展示的号段" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "不透明号段ID，原样用于selected_cidr_id" }, "cidr": { "type": "string", "description": "CIDR号段，例如192.0.2.0/24" }, "available_count": { "type": "integer", "description": "此号段可售库存参考值" } } } } } } } } }