# 集成流程 先读取目录或已验证范围，核对报价或 revision，只提交一次，再跟踪已保存操作和交付状态。 ## 目录与购买 ```text products → catalog → quote → purchase ↓ purchase_status → order_delivery → order_proxies ``` 多国购买会生成各国独立订单及一张多行发票，折扣按国家计算。accepted 表示已入队接受，不表示已交付。 ## 续期 ```text renewal_options → renewal_quote → renewal → renewal_status ``` ## 额外登录 ```text extra_login_options → extra_login_create → extra_login_operation_status ``` ## 住宅代理列表与流量 ```text residential_catalog → residential_quote → residential_purchase ↓ residential_purchase_status → order_delivery → residential_package_refresh ``` ## Idempotency-Key 每个预期写操作应保存一个 Idempotency-Key。超时或 HTTP 5xx 不代表失败。请用同一键查询状态，不要为了处理不确定结果而用新键重做操作。 - [**查询购买状态 →****GET** `/orders/create/status`](https://docs.arnproxy.com/zh/api-v1/orders/create/status) - [**续期状态 →****GET** `/renewals/status`](https://docs.arnproxy.com/zh/api-v1/renewals/status) - [**查询登录操作 →****GET** `/extra-logins/status`](https://docs.arnproxy.com/zh/api-v1/proxies/extra-logins/status) - [**住宅代理交付状态 →****GET** `/residential/orders/status`](https://docs.arnproxy.com/zh/api-v1/residential/orders/status) --- [ARNPROXY API](https://docs.arnproxy.com/zh/api-v1/workflows) ## 使用用途：只需选择子用途 标准订单不应让客户选择两次。请在 catalog.purposes 中找到 id=201，并仅展示其 children。purchase 中的 purpose_id 固定为整数 201，subpurpose_id 为所选子项的 ID。保留层级结构是为了兼容现有集成。 quote 的订单行不包含用途，只需 location_id、time_id 和 quantity。用途字段在 purchase 阶段必填。 ```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。 ```json { "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。每个国家生成独立订单，关联结账按一张发票处理。数量折扣按每个国家自己的数量计算。 ```json { "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 } ``` ## 住宅代理：新套餐与流量追加 · mode=new 购买 Residential 代理时，客户无需选择用途。新套餐由服务器自动使用与网站订单相同的固定用途；无需发送 purpose_id、subpurpose_id 或 other_purpose。流量充值保留现有套餐的用途。 ```json { "mode": "new", "location_id": 20, "time_id": 201, "promo_code": "", "currency": "TRY", "expected_total_minor": 1000, "expected_selection_hash": "0000000000000000000000000000000000000000000000000000000000000000", "terms": false } ``` ## 住宅代理：新套餐与流量追加 · mode=topup 购买 Residential 代理时，客户无需选择用途。新套餐由服务器自动使用与网站订单相同的固定用途；无需发送 purpose_id、subpurpose_id 或 other_purpose。流量充值保留现有套餐的用途。 ```json { "mode": "topup", "package_id": 10001, "time_id": 201, "promo_code": "", "currency": "TRY", "expected_total_minor": 1000, "expected_selection_hash": "0000000000000000000000000000000000000000000000000000000000000000", "terms": false } ``` ## CSV 导出 CSV 列可从 id、endpoint、ip、port、login 和 password 中选择。自定义格式只接受文档列出的 %...% 占位符，不执行代码。包含凭据的输出需要 credentials 权限。内容返回在 JSON 内，由您的应用保存为文件。 ```json { "proxy_ids": [ 10001 ], "format": "csv", "columns": [ "id", "endpoint" ] } ``` ## 自定义连接格式 CSV 列可从 id、endpoint、ip、port、login 和 password 中选择。自定义格式只接受文档列出的 %...% 占位符，不执行代码。包含凭据的输出需要 credentials 权限。内容返回在 JSON 内，由您的应用保存为文件。 ```json { "proxy_ids": [ 10001 ], "format": "custom", "template": "%login%:%password%@%endpoint%" } ``` ## 已受理不等于已交付 HTTP 201/202 或 state=accepted 可能仅表示受理。使用 purchase_status / residential_purchase_status 跟踪同一次操作，使用 order_delivery 跟踪交付。遵守返回的 poll_after_seconds 和 Retry-After。超时后不要换一个 Idempotency-Key 重新购买。