Integration workflows
Read the catalog or verified scope first, review the quote or revision, submit once, then follow the saved operation and delivery state.
Catalog & purchases
products → catalog → quote → purchase
↓
purchase_status → order_delivery → order_proxiesA multi-country purchase produces separate country orders and one multi-line invoice. Discounts are calculated per country. accepted means queued acceptance, not completed delivery.
Renewals
renewal_options → renewal_quote → renewal → renewal_statusExtra logins
extra_login_options → extra_login_create → extra_login_operation_statusResidential lists & traffic
residential_catalog → residential_quote → residential_purchase
↓
residential_purchase_status → order_delivery → residential_package_refreshIdempotency-Key
Persist one Idempotency-Key for each intended write. A timeout or HTTP 5xx does not prove failure. Query its status with the same key; never start a replacement write with a new key to resolve uncertainty.
/orders/create/statusSaved renewal result →GET /renewals/statusReconcile the same extra-login operation →GET /extra-logins/statusSaved acceptance and current Residential delivery state →GET /residential/orders/statusUsage purpose: select only the subpurpose
Do not ask customers to make two selections for a standard order. Find id=201 in catalog.purposes and display only its children. In purchase, purpose_id is the fixed integer 201 and subpurpose_id is the selected child ID. The hierarchical catalog shape remains for compatibility with existing integrations.
Quote lines do not take a purpose: location_id, time_id and quantity are sufficient. Purpose fields are required at the purchase stage.
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.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.The “Other” purpose
For Other, send subpurpose_id=-1 and other_purpose containing 1–30 characters. Other selections do not require other_purpose. purpose_id remains 201.
{
"location_id": 10,
"time_id": 101,
"quantity": 1,
"purpose_id": 201,
"subpurpose_id": -1,
"other_purpose": "Custom purpose"
}Residential: new package versus GB top-up
Customers do not select a purpose for Residential orders. For a new package, the server automatically assigns the same fixed purpose as the website checkout; do not send purpose_id, subpurpose_id or other_purpose. A top-up preserves the existing package purpose.
IDs and prices are illustrative; use real values from the catalog and the same quote. JSON IDs and expected_total_minor must be numbers. Examples deliberately keep terms=false; submit terms=true only after explicit customer approval for the real paid operation.
One product type, two countries
Use up to 20 distinct location_id values under one product_id. Each country creates a separate order record; the linked checkout is handled as one invoice. Quantity discounts are calculated independently per country.
{
"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
Residential: new package versus GB top-up · mode=new
Customers do not select a purpose for Residential orders. For a new package, the server automatically assigns the same fixed purpose as the website checkout; do not send purpose_id, subpurpose_id or other_purpose. A top-up preserves the existing package purpose.
{
"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
Residential: new package versus GB top-up · mode=topup
Customers do not select a purpose for Residential orders. For a new package, the server automatically assigns the same fixed purpose as the website checkout; do not send purpose_id, subpurpose_id or other_purpose. A top-up preserves the existing package purpose.
{
"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 export
Choose CSV columns from id, endpoint, ip, port, login and password. Custom formats accept only the documented %...% tokens and never execute code. Credential-bearing output requires credentials permission. The content is returned inside JSON; your application saves it to a file.
{
"proxy_ids": [
10001
],
"format": "csv",
"columns": [
"id",
"endpoint"
]
}POST /account/api/v1/proxies/export
Custom connection format
Choose CSV columns from id, endpoint, ip, port, login and password. Custom formats accept only the documented %...% tokens and never execute code. Credential-bearing output requires credentials permission. The content is returned inside JSON; your application saves it to a file.
{
"proxy_ids": [
10001
],
"format": "custom",
"template": "%login%:%password%@%endpoint%"
}POST /account/api/v1/proxies/export
Accepted does not mean delivered
HTTP 201/202 or state=accepted may confirm acceptance only. Follow the same operation with purchase_status / residential_purchase_status and fulfillment with order_delivery. Honor poll_after_seconds and Retry-After when present. Do not repurchase under a new Idempotency-Key after a timeout.