DF-IP 用户 API 接入指南

本文介绍 DF-IP 面向用户程序的 API：查询动态代理地区、生成动态代理连接信息，以及查询和购买静态住宅代理。

1. 准备 API Key 和接口地址

登录 DF-IP 网页端，在个人中心复制自己的 API Key；在「API 接口」页面查看当前对外接口地址。本文以 https://YOUR_API_HOST 作为占位地址，请替换为页面显示的实际域名。帮助中心域名不等于业务 API 域名。

请从自己的服务器调用 HTTPS 接口，通过环境变量或密钥管理工具保存 API Key，不要把它写进公开网页、源码仓库或日志。返回的代理账号和密码同样需要保密。

2. 接口与鉴权对照

动态提取接口目前不从 Api-Token 请求头取凭证。建议使用 POST 表单传递 token，减少密钥进入 URL 历史及访问日志的机会；请求正文也应避免被日志系统记录。不要把帮助中心发布凭证或网页登录 Token 当作业务 API Key。

3. 发起第一个只读请求

以下示例使用 Bash 与 curl。先将 DFIP_API_KEY 安全注入当前环境，再配置实际 API 地址；不要在终端历史里粘贴真实密钥。

export DFIP_API_BASE='https://YOUR_API_HOST'
curl --silent --show-error --max-time 30 \
  "$DFIP_API_BASE/api/user/v1/account/balance" \
  -H "Api-Token: $DFIP_API_KEY"

检查 HTTP 状态和 JSON 中的 code：code: 0 表示业务请求成功，数据位于 data，提示位于 msg。失败时不要仅凭 HTTP 200 判定成功；动态接口的业务错误也可能使用 HTTP 200。

{"code":0,"msg":"success","data":{}}

上面仅展示响应结构；真实字段随接口变化。本文所有域名、账号、任务号和数据示例均为占位值，不代表实时库存、价格或实际订单。

4. 静态住宅接口权限

购买权限必须显式开通。部分历史 Key 兼容只读权限，但不能据此认为可以购买；以余额接口返回的 scopes 和实际授权为准。配置了 IP 白名单的静态 API Key，需要从允许的公网出口调用；子账号还需具备静态住宅权限。

共享余额子账号的 balance_source 可以为 parent，表示使用主账号余额；订单归属和 IP 可见范围仍按当前调用账号控制。静态购买可用金额见 static_purchase_available_balance，不要自行把赠送余额和佣金余额相加作为购买预算。

5. 按业务接入

1. 动态代理：先查地区，保存返回的 value，再生成代理连接字符串；把返回的主机、端口、用户名、密码配置到支持对应协议的软件。
2. 静态住宅：查询库存与业务名称 → 获取报价 → 核对金额 → 使用唯一幂等键提交购买 → 查询任务 → 确认 completed → 查询已购 IP。

涉及购买的接口会创建实际购买任务并可能扣款；不要用自动重发新幂等键的方法测试。HTTP 202 只说明请求已被接受，并不代表代理已交付。

静态列表使用 page、page_size 分页，默认 1、20，单页最多 100。动态地区列表返回 count 与 list，不使用这套分页字段。

6. 出错与重试

• 401 或凭证错误：检查 Key 是否正确、启用、过期，以及凭证是否放在正确位置。
• 403：检查 Scope、IP 白名单、账号状态和子账号权限。
• 400：修正参数；不要原样高频重试。
• 429：降低频率，若提供 Retry-After 则按其等待。配额以实际服务响应为准。
• 5xx 或网络超时：只读请求可以退避重试；购买必须保留原幂等键并查询原任务。

动态接口可用 Accept-Language: zh-CN、zh-HK、en 请求提示语言。静态 V1 当前部分错误提示固定为中文，程序应根据 code 分支处理，不要依赖 msg 的语言或完整文字。

文档目录

• 动态代理地区查询
• 动态代理提取
• 静态住宅：余额、库存、订单与 IP 查询
• 静态住宅：报价、购买与任务状态

English version