静态住宅 API：余额、库存、订单与 IP 查询
查询余额、可售国家城市、业务名称、订单和已购 IP，了解分页、协议位掩码与凭证字段。
本文覆盖账户余额、静态住宅库存、业务名称、自己的订单和已购 IP 查询。所有路径均基于网页端显示的业务 API 域名，统一使用 Api-Token: YOUR_API_KEY 请求头。
接口总览
| 方法 | 路径 | Scope |
|---|---|---|
| GET | /api/user/v1/account/balance | account:read |
| GET | /api/user/v1/static-residential/countries | static:inventory:read |
| GET | /api/user/v1/static-residential/cities | static:inventory:read |
| GET | /api/user/v1/static-residential/inventory | static:inventory:read |
| GET | /api/user/v1/static-residential/business-names | static:inventory:read |
| GET | /api/user/v1/static-residential/orders | static:ip:read |
| GET | /api/user/v1/static-residential/ips | static:ip:read |
| GET | /api/user/v1/static-residential/ips/{id} | static:ip:read |
成功响应为 {"code":0,"msg":"success","data":{...}}。HTTP 错误或非零 code 均需处理。
1. 余额
GET /api/user/v1/account/balance，无业务参数。
data 字段 | 说明 |
|---|---|
user_uuid | 当前调用账号的标识 |
balance | 有效账户余额 |
gift_balance | 赠送余额 |
commission_balance | 佣金余额 |
static_purchase_available_balance | 静态购买可用余额，当前取 balance |
balance_source | self 自己；parent 共享主账号余额 |
scopes | 当前 Key 权限列表 |
currency | USD |
余额不是价格承诺，也不会因为读取而预留资金；报价与购买之间余额可能变化。
2. 国家、城市和库存
国家接口返回 items、total、cache_status。每个国家包含 country_code、country_name、country_name_cn、country_name_hk 和 stock。
城市接口必须带两位国家代码 country_code，例如 US。返回 country_code、items、total、cache_status。
库存接口支持以下查询参数：
| 参数 | 说明 |
|---|---|
country_code | 可选，两位国家代码 |
city_name | 可选，城市名关键词，按包含关系筛选 |
page | 默认 1，最小 1 |
page_size | 默认 20，范围 1–100 |
城市与库存的每个条目包含 continent_name、country_code、city_name、stock、monthly_price、currency。库存接口返回 items、pagination、cache_status。
curl --silent --show-error --get \
"$DFIP_API_BASE/api/user/v1/static-residential/inventory" \
-H "Api-Token: $DFIP_API_KEY" \
--data-urlencode 'country_code=US' \
--data-urlencode 'page=1' --data-urlencode 'page_size=20'
US 仅作代码格式示例，实际可售地区以查询结果为准。库存及月价可能来自缓存；购买前应获取新报价，并原样使用返回的城市名。不要手动修正拼写、翻译城市名或把动态地区的城市 code 用到静态报价中。
3. 业务名称
GET /api/user/v1/static-residential/business-names，无业务参数。
data.items 中每项包含 business_name、category、is_hot，另有 data.default，当前为 other。报价时应选用当前列表中的 business_name；不要自行生成或翻译接口值。
4. 自己的静态住宅订单
GET /api/user/v1/static-residential/orders?page=1&page_size=20
只返回当前调用账号的静态住宅订单。data.items 每项包含：
| 字段 | 含义 |
|---|---|
order_id | 业务订单号，可与购买任务的 local_order_id 对照 |
total_amount、unit_price | 订单金额、单价 |
ip_quantity | IP 数量 |
payment_status、order_type | 订单系统数值字段；不能当作异步任务状态 |
purchase_duration | 购买期限字段 |
created_at、updated_at | 创建、更新时间 |
不要仅凭订单条目存在就判定交付完成；购买任务应达到 completed，再核对已购 IP。
5. 已购 IP 列表与详情
GET /api/user/v1/static-residential/ips
| 查询参数 | 说明 |
|---|---|
status | active、expired、all；省略也表示不按状态筛选 |
country_code | 可选，两位国家代码 |
city | 可选，城市关键词；这里叫 city，不是库存接口的 city_name |
ip_address | 可选，IP 字符串关键词 |
page、page_size | 通用分页 |
详情接口 GET /api/user/v1/static-residential/ips/{id} 使用列表返回的正整数 id，不是 IP 地址，也不是订单号。查询仅限当前账号持有的静态住宅记录。
curl --silent --show-error --get \
"$DFIP_API_BASE/api/user/v1/static-residential/ips" \
-H "Api-Token: $DFIP_API_KEY" \
--data-urlencode 'status=active' \
--data-urlencode 'page=1' --data-urlencode 'page_size=20'
列表 data.items[] 与详情 data 使用相同条目结构：
| 字段 | 说明 |
|---|---|
id、order_id、ip_address | 记录 ID、订单号、代理地址 |
proxy_username、proxy_password | 代理认证信息，请勿公开 |
proxy_protocol | 协议位掩码：1=HTTP、2=HTTPS、4=SOCKS5，5=HTTP+SOCKS5；不同于报价请求中的协议名称 |
http_port、https_port、s5_port | 对应端口，未提供时可为 0 或 null；仅使用大于 0 且产品支持的端口；当前静态购买支持 HTTP/SOCKS5 |
country_code、country、state、city | 地区信息 |
status | active 或 expired；失效或过期记录归为 expired |
is_renewable、is_auto_renew | 续费能力和自动续费标记，只读；不代表存在修改接口 |
remark | 备注 |
expiry_at、created_at、updated_at | 到期、创建、更新时间 |
日期字符串不带时区偏移；需计算精确到期时间时，请确认服务端使用的时区，不要直接视为 UTC。
分页与错误
pagination 包含 page、page_size、total、total_pages；空结果时 total 和 total_pages 为 0。国家、城市、业务名称接口不使用分页。
常见 code：40001 国家代码错误；40006 IP 记录 ID 无效；40007 状态筛选值错误；40402 记录不存在或不可访问；50301 库存服务暂不可用；50302 业务名称加载失败。鉴权失败处理见接入指南。
报价和购买 · 接入指南 · English version