集成流程

先读取目录或已验证范围，核对报价或 revision，只提交一次，再跟踪已保存操作和交付状态。

目录与购买

API v1

products → catalog → quote → purchase
                         ↓
purchase_status → order_delivery → order_proxies

多国购买会生成各国独立订单及一张多行发票，折扣按国家计算。accepted 表示已入队接受，不表示已交付。

续期

API v1

renewal_options → renewal_quote → renewal → renewal_status

额外登录

API v1

extra_login_options → extra_login_create → extra_login_operation_status

住宅代理列表与流量

API v1

residential_catalog → residential_quote → residential_purchase
                                              ↓
residential_purchase_status → order_delivery → residential_package_refresh

Idempotency-Key

每个预期写操作应保存一个 Idempotency-Key。超时或 HTTP 5xx 不代表失败。请用同一键查询状态，不要为了处理不确定结果而用新键重做操作。

查询购买状态 →GET /orders/create/status续期状态 →GET /renewals/status查询登录操作 →GET /extra-logins/status住宅代理交付状态 →GET /residential/orders/status

使用用途：只需选择子用途

标准订单不应让客户选择两次。请在 catalog.purposes 中找到 id=201，并仅展示其 children。purchase 中的 purpose_id 固定为整数 201，subpurpose_id 为所选子项的 ID。保留层级结构是为了兼容现有集成。

quote 的订单行不包含用途，只需 location_id、time_id 和 quantity。用途字段在 purchase 阶段必填。

Node.js / JavaScript

const response = await fetch(
  'https://www.arnproxy.com/account/api/v1/catalog?product_id=' + productId,
  { headers: { Authorization: 'Bearer ' + apiKey } }
);
const catalog = await response.json();
if (!response.ok || !catalog.ok) throw new Error('Catalog request failed');
const purposeGroup = catalog.data.purposes.find(group => group.id === 201);
if (!purposeGroup) throw new Error('Purpose group 201 is not available');
const purposeOptions = purposeGroup.children.map(({ id, name }) => ({ id, name }));
// Show only purposeOptions. The customer selects selectedSubpurposeId.
const purchaseLine = {
  location_id: selectedLocationId,
  time_id: selectedTimeId,
  quantity: selectedQuantity,
  purpose_id: 201,
  subpurpose_id: selectedSubpurposeId
};
// Add other_purpose (1–30 characters) only when selectedSubpurposeId === -1.
// No purchase is sent by this example.

Python

import json
import urllib.request

request = urllib.request.Request(
    'https://www.arnproxy.com/account/api/v1/catalog?product_id=' + str(product_id),
    headers={'Authorization': 'Bearer ' + api_key}
)
with urllib.request.urlopen(request, timeout=20) as response:
    catalog = json.load(response)
if not catalog.get('ok'):
    raise RuntimeError('Catalog request failed')
purpose_group = next((g for g in catalog['data']['purposes'] if g['id'] == 201), None)
if purpose_group is None:
    raise RuntimeError('Purpose group 201 is not available')
purpose_options = [{'id': p['id'], 'name': p['name']} for p in purpose_group['children']]
# Display only purpose_options; the customer selects selected_subpurpose_id.
purchase_line = {
    'location_id': selected_location_id,
    'time_id': selected_time_id,
    'quantity': selected_quantity,
    'purpose_id': 201,
    'subpurpose_id': selected_subpurpose_id,
}
# For Other (-1), also set other_purpose to 1–30 characters.
# This example does not submit a purchase.

“其他”用途

选择“其他”时，发送 subpurpose_id=-1 和包含 1–30 个字符的 other_purpose。其他选项无需 other_purpose。purpose_id 仍为 201。

purchase · lines[]

{
    "location_id": 10,
    "time_id": 101,
    "quantity": 1,
    "purpose_id": 201,
    "subpurpose_id": -1,
    "other_purpose": "Custom purpose"
}

住宅代理：新套餐与流量追加

购买 Residential 代理时，客户无需选择用途。新套餐由服务器自动使用与网站订单相同的固定用途；无需发送 purpose_id、subpurpose_id 或 other_purpose。流量充值保留现有套餐的用途。

ID 和价格仅供示例，请使用目录及同一次报价中的实际值。JSON ID 和 expected_total_minor 必须是数字。示例刻意保留 terms=false；只有客户明确同意实际付费操作后才应发送 terms=true。

同一产品类型的两个国家

一个 product_id 下最多可包含 20 个不同的 location_id。每个国家生成独立订单，关联结账按一张发票处理。数量折扣按每个国家自己的数量计算。

POST /orders/create

{
    "product_id": 5,
    "lines": [
        {
            "location_id": 10,
            "time_id": 101,
            "quantity": 1,
            "purpose_id": 201,
            "subpurpose_id": 202
        },
        {
            "location_id": 11,
            "time_id": 102,
            "quantity": 1,
            "purpose_id": 201,
            "subpurpose_id": 202
        }
    ],
    "currency": "TRY",
    "expected_total_minor": 2000,
    "promo_code": "",
    "terms": false
}

POST /account/api/v1/orders/create

住宅代理：新套餐与流量追加 · mode=new

POST /residential/orders/create

{
    "mode": "new",
    "location_id": 20,
    "time_id": 201,
    "promo_code": "",
    "currency": "TRY",
    "expected_total_minor": 1000,
    "expected_selection_hash": "0000000000000000000000000000000000000000000000000000000000000000",
    "terms": false
}

POST /account/api/v1/residential/orders/create

住宅代理：新套餐与流量追加 · mode=topup

POST /residential/orders/create

{
    "mode": "topup",
    "package_id": 10001,
    "time_id": 201,
    "promo_code": "",
    "currency": "TRY",
    "expected_total_minor": 1000,
    "expected_selection_hash": "0000000000000000000000000000000000000000000000000000000000000000",
    "terms": false
}

POST /account/api/v1/residential/orders/create

CSV 导出

CSV 列可从 id、endpoint、ip、port、login 和 password 中选择。自定义格式只接受文档列出的 %...% 占位符，不执行代码。包含凭据的输出需要 credentials 权限。内容返回在 JSON 内，由您的应用保存为文件。

POST /proxies/export

{
    "proxy_ids": [
        10001
    ],
    "format": "csv",
    "columns": [
        "id",
        "endpoint"
    ]
}

POST /account/api/v1/proxies/export

自定义连接格式

POST /proxies/export

{
    "proxy_ids": [
        10001
    ],
    "format": "custom",
    "template": "%login%:%password%@%endpoint%"
}

POST /account/api/v1/proxies/export

已受理不等于已交付

HTTP 201/202 或 state=accepted 可能仅表示受理。使用 purchase_status / residential_purchase_status 跟踪同一次操作，使用 order_delivery 跟踪交付。遵守返回的 poll_after_seconds 和 Retry-After。超时后不要换一个 Idempotency-Key 重新购买。