静态住宅 API：报价、购买与任务状态

静态住宅购买分为报价、提交任务和查询结果。报价不会直接购买；提交订单会创建真实购买任务并可能扣款。请先确认购买地区、数量、业务名称和总金额。

1. 接口与权限

所有请求使用业务 API 域名和 Api-Token: YOUR_API_KEY。

POST 请求使用 Content-Type: application/json。查询已交付 IP 还需要 static:ip:read。使用旧 Key 能查询库存，不代表已经获得购买权限。

2. 获取报价

先从国家、城市/库存和业务名称接口选择真实可用值，再提交：

以下 COUNTRY_CODE、CITY_NAME、BUSINESS_NAME 都必须替换为查询返回值。代码中的购买金额不由客户端指定。

curl --silent --show-error --max-time 30 \
  "$DFIP_API_BASE/api/user/v1/static-residential/quotes" \
  -H "Api-Token: $DFIP_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"country_code":"COUNTRY_CODE","city_name":"CITY_NAME","quantity":1,"duration_days":30,"business_name":"BUSINESS_NAME","protocol":"both"}'

成功 data 包含 quote_id、country_code、city_name、quantity、duration_days、business_name、protocol、unit_price、total_amount、currency 和 expires_in。

报价有效期为 300 秒，属于当前调用账号。币种为 USD。提交前展示并核对 total_amount；报价校验当前库存与价格，但不锁定库存或预留账户余额。过期后需要重新报价并重新核对金额。

3. 使用幂等键提交购买

请求头 Idempotency-Key 必填：8–64 个字符，仅可使用字母、数字、点、下划线、冒号和连字符。

在发请求之前保存幂等键、购买意图和 quote_id。 每一笔有意发起的新购买使用一个新键；同一笔购买的网络重试复用原键，不要每次请求都随机生成新键。

# Use a unique key for a new purchase and retain it for retries.
export DFIP_PURCHASE_KEY='YOUR_UNIQUE_PURCHASE_KEY'
curl --silent --show-error --max-time 30 \
  "$DFIP_API_BASE/api/user/v1/static-residential/orders" \
  -H "Api-Token: $DFIP_API_KEY" \
  -H "Idempotency-Key: $DFIP_PURCHASE_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"quote_id":"YOUR_QUOTE_ID"}'

成功返回 HTTP 202、code: 0，以及任务 operation_no、status 等字段。此时不能把它显示为“购买成功”。

当前账号相同幂等键已有任务时，接口会返回原任务，即使旧报价已过期。不要把一个旧键用于另一笔购买，也不要依赖服务端一定会为新的参数返回冲突；调用端必须自己保存并核对键与购买意图的绑定关系。

4. 查询任务与确认交付

curl --silent --show-error --max-time 30 \
  "$DFIP_API_BASE/api/user/v1/static-residential/operations/YOUR_OPERATION_NO" \
  -H "Api-Token: $DFIP_API_KEY"

建议从每 2–5 秒查询一次开始，等待时间变长时逐步退避。这是调用建议，不是固定服务配额。每次请求使用原 operation_no。

任务 data 包含：operation_no、status、message、country_code、city_name、quantity、duration_days、business_name、amount、local_order_id、created_at、completed_at。订单号和完成时间在尚未生成时可为 null。

amount 表示报价金额，不是“已经扣款”的证明；结合状态及账户记录核对。completed 后到 已购 IP 查询 获取代理账号、密码和端口。轮询等待超时也不代表任务失败，应保留原任务继续跟踪。

5. 错误处理

鉴权服务暂不可用可能返回 503 / 50300；缺失或失效 Key 返回 401 / 40101、40102。出现网络超时、响应丢失或服务异常时，不应自动换新幂等键重新买。

接入检查清单

1. 金额和地区经确认后才提交购买。
2. 本地持久保存幂等键与购买参数，获得响应后保存 operation_no。
3. HTTP 202 进入处理中；只有 completed 进入已完成。
4. 对 reconcile_required 停止自动重买，转人工核验。
5. 不把代理密码、API Key 或完整响应写到公开日志。

当前这组开放 API 提供购买与查询，不提供续费、自动续费开关、删除或换 IP 接口；这些操作请使用控制台已有功能。

查询接口参考 · 接入指南 · English version