海外订单查询接口

更新时间：2026-07-09

本文档介绍订单查询接口，支持通过套餐类型（mealType）区分静态与动态订单，提供分页、时间范围筛选及订单详情查询功能。

一、公共说明

1.1 请求域名

所有 OpenAPI 接口统一通过以下域名访问：

https://openapi.fanproxy.com

1.2 请求头要求

所有 OpenAPI 接口均通过网关（Gateway）进行签名认证，请求必须携带以下请求头。

必填请求头

请求头名称	类型	必填	说明
X-Api-Key	String	是	用户账号，即手机号
X-Api-Signature	String	是	API 签名凭证，由平台生成，可前往官网控制台查看
X-Api-Timestamp	String	是	请求时间戳（秒），用于防重放攻击

请求头示例

POST /open-api/open/overseas/subaccount/add HTTP/1.1
Host: openapi.fanproxy.com
Content-Type: application/json
X-Api-Key: your_api_key_here
X-Api-Signature: your_signature_here
X-Api-Timestamp: 1711000000

1.3 统一响应格式

所有接口均返回统一的 JSON 结构，便于客户端统一解析处理：

响应字段说明

字段	类型	说明
code	Integer	状态码，200 表示成功
success	Boolean	操作是否成功，true / false
data	Object/Array/null	响应数据，成功时返回业务数据，失败时为 null
message	String	错误描述信息，成功时为 null

成功响应示例

{
  "code": 200,
  "success": true,
  "data": { ... },
  "message": null
}

失败响应示例

{
  "code": 20000102,
  "success": false,
  "data": null,
  "message": "子账号不存在"
}

1.4 错误码说明

业务层统一使用 OpenApiApiExceptionEnum（一般为 2000xxxx 段）。部分接口在调用内部 Facade 失败时，会透传下游返回的 code 与 message（非 200 且非下表枚举值时，以响应体为准）。

全局错误码表

错误码	说明	来源
200	成功	业务层
401	签名认证失败（缺少 Key、签名无效、请求过期、重复请求等）	网关层
20000001	用户信息缺失（如缺少 X-Api-User-Id）	业务层（@OpenApiAuth 校验 / 子账号锁）
20000002	缺少开放接口账号头信息（缺少 X-Api-App-Key）	业务层（@OpenApiAuth）
20000003	用户中心查询失败	业务层（@OpenApiAuth）
20000004	密钥与签名归属账号不一致	业务层（@OpenApiAuth）
20000005	系统繁忙，请稍后重试（或同类前缀的详细 message）	业务层（通用失败/异常兜底）
20000101	操作频繁，请稍候（子账号接口分布式锁未获取到）	业务层
20000102	子账号不存在	业务层
20000301	未找到指定的子账号（认证账号流量信息）	业务层
20001001~20001014	参数校验（账户名、密码、套餐类型、时间等；含流量记录时间窗与区间）	业务层
20002001	无效的套餐类型（订单查询 mealType）	业务层
其他整数	内部服务 R 返回的非 200 code	下游 Facade

网关认证失败（401）时的响应体格式：

{
  "code": 401,
  "message": "缺少X-Api-Key请求头",
  "timestamp": 1711000000000,
  "path": "/open-api/open/overseas/subaccount/add",
  "authType": "api_sign",
  "traceId": "abc-123"
}

二、订单查询

接口地址：POST /open-api/open/order/query

接口描述：统一订单查询接口，通过 mealType 区分不同类型的订单，支持分页和时间范围筛选。

2.1 请求参数（Body - JSON）

参数名	类型	必填	说明
mealType	Integer	是	套餐类型：1-住宅/共享/双 ISP，2-住宅/共享/原生双 ISP，3-住宅/独享，4-数据中心/共享/IPv4，5-TikTok，6-海外动态/标准，7-海外动态/企业，8-海外动态/基础，9-海外动态/不限量，10-海外动态/长效 ISP
orderNo	String	否	订单编号，精确查询
pageNum	Integer	否	分页页码，默认第 1 页
pageSize	Integer	否	分页大小，默认 20 条
startTime	Long	否	查询起始时间（秒时间戳）
endTime	Long	否	查询结束时间（秒时间戳）

2.2 请求示例

{
  "mealType": 1,
  "pageNum": 1,
  "pageSize": 20,
  "startTime": 1709222400,
  "endTime": 1710835199
}

2.3 返回字段说明（data 字段）

字段名	类型	说明
data	List<OrderItem>	订单列表
pageNum	Integer	当前页码
pageSize	Integer	每页条数
totalPage	Integer	总页数
totalSize	Integer	总条数

OrderItem 通用字段说明

字段名	类型	说明
orderNo	String	订单编号
state	Integer	订单状态：1-待支付，2-已支付，3-已取消
amount	BigDecimal	支付金额（元）
payType	Integer	支付方式
createTime	Long	订单创建时间（秒时间戳）
buyTime	Integer	时长（天）
bandwidth	Integer	购买带宽（MB）

OrderItem 静态订单专属字段（mealType 1~5）

字段名	类型	说明
countryName	String	国家地区
ipNum	Integer	购买 IP 数量

OrderItem 动态订单专属字段（mealType 6~10）

字段名	类型	说明
buyFlow	BigDecimal	购买流量（G）
giftFlow	BigDecimal	赠送流量（G）
balance	BigDecimal	购买后账户余量（G）

2.4 返回示例（静态订单）

{
  "code": 200,
  "success": true,
  "data": {
    "data": [
      {
        "orderNo": "ORD20260318001",
        "state": 2,
        "amount": 100.00,
        "payType": 1,
        "createTime": 1710739200,
        "buyTime": 30,
        "bandwidth": 100,
        "countryName": "美国",
        "ipNum": 5,
        "buyFlow": null,
        "giftFlow": null,
        "balance": null
      }
    ],
    "pageNum": 1,
    "pageSize": 20,
    "totalPage": 1,
    "totalSize": 1
  },
  "message": null
}

2.5 返回示例（动态订单）

{
  "code": 200,
  "success": true,
  "data": {
    "data": [
      {
        "orderNo": "ORD20260318002",
        "state": 2,
        "amount": 50.00,
        "payType": 1,
        "createTime": 1710739200,
        "buyTime": null,
        "bandwidth": null,
        "countryName": null,
        "ipNum": null,
        "buyFlow": 100.00,
        "giftFlow": 10.00,
        "balance": 85.50
      }
    ],
    "pageNum": 1,
    "pageSize": 20,
    "totalPage": 1,
    "totalSize": 1
  },
  "message": null
}

2.6 错误码

错误码	说明 / 触发条件
200	成功
401	网关签名认证失败
20000001	缺少 X-Api-User-Id
20000002	缺少 X-Api-App-Key
20000003	用户中心查询失败
20000004	密钥与签名归属账号不一致
20001008	mealType 为空
20002001	mealType 不在允许范围（1～10），message 含无效值
非 200	webPageQuery 失败时透传下游 code 与 message
20000005	未捕获异常（message 如「查询订单异常: …」，含 customerId 非数字等运行时错误）

国内固定IP查询