Integrationsabläufe

Zuerst Katalog oder verifizierten Umfang lesen, Angebot oder Revision prüfen, einmal absenden und gespeicherten Vorgang sowie Lieferung verfolgen.

Katalog und Bestellungen

API v1

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

Ein Mehrländer-Kauf erzeugt getrennte Länderbestellungen und eine Rechnung mit mehreren Positionen. Rabatte gelten je Land. accepted bedeutet Annahme in die Warteschlange, nicht Lieferung.

Verlängerungen

API v1

renewal_options → renewal_quote → renewal → renewal_status

Zusätzliche Logins

API v1

extra_login_options → extra_login_create → extra_login_operation_status

Residential-Listen und Traffic

API v1

residential_catalog → residential_quote → residential_purchase
                                              ↓
residential_purchase_status → order_delivery → residential_package_refresh

Idempotency-Key

Speichern Sie pro beabsichtigter Änderung einen Idempotency-Key. Timeout oder HTTP 5xx beweist keinen Fehlschlag. Fragen Sie den Status mit demselben Schlüssel ab; starten Sie bei Unklarheit keinen neuen Schreibvorgang.

Kaufstatus prüfen →GET /orders/create/statusVerlängerungsstatus →GET /renewals/statusLogin-Vorgang prüfen →GET /extra-logins/statusResidential-Lieferstatus →GET /residential/orders/status

Verwendungszweck: nur Unterzweck auswählen

Verlangen Sie bei einer Standardbestellung keine zwei Auswahlen. Suchen Sie id=201 in catalog.purposes und zeigen Sie nur dessen children an. Bei purchase ist purpose_id die feste Ganzzahl 201; subpurpose_id ist die ID des gewählten Unterzwecks. Die Hierarchie bleibt für bestehende Integrationen erhalten.

Für quote enthalten die Positionen keinen Verwendungszweck: location_id, time_id und quantity reichen aus. Die Zweckfelder sind bei purchase erforderlich.

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.

Verwendungszweck „Sonstiges“

Für Sonstiges senden Sie subpurpose_id=-1 und other_purpose mit 1–30 Zeichen. Bei anderen Auswahlen ist other_purpose nicht erforderlich. purpose_id bleibt 201.

purchase · lines[]

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

Residential: neues Paket oder GB-Aufladung

Bei Residential-Bestellungen wählen Kunden keinen Verwendungszweck. Für ein neues Paket weist der Server automatisch denselben festen Zweck wie beim Website-Kauf zu; senden Sie weder purpose_id noch subpurpose_id oder other_purpose. Eine Traffic-Aufladung behält den bisherigen Zweck bei.

IDs und Preise sind beispielhaft; verwenden Sie echte Werte aus dem Katalog und demselben Angebot. JSON-IDs und expected_total_minor müssen Zahlen sein. Beispiele verwenden bewusst terms=false. Senden Sie terms=true nur nach ausdrücklicher Zustimmung zur kostenpflichtigen Aktion.

Ein Produkttyp, zwei Länder

Verwenden Sie bis zu 20 verschiedene location_id unter einem product_id. Jedes Land erzeugt eine eigene Bestellung; der verknüpfte Einkauf wird in einer Rechnung behandelt. Mengenrabatte werden pro Land berechnet.

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

Residential: neues Paket oder GB-Aufladung · 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

Residential: neues Paket oder GB-Aufladung · 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-Export

Wählen Sie CSV-Spalten aus id, endpoint, ip, port, login und password. Eigene Formate erlauben nur dokumentierte %...%-Platzhalter und führen keinen Code aus. Zugangsdaten erfordern die Berechtigung credentials. Der Inhalt kommt in JSON; Ihre Anwendung speichert die Datei.

POST /proxies/export

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

POST /account/api/v1/proxies/export

Eigenes Verbindungsformat

POST /proxies/export

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

POST /account/api/v1/proxies/export

Angenommen bedeutet nicht geliefert

HTTP 201/202 oder state=accepted kann nur die Annahme bestätigen. Verfolgen Sie denselben Vorgang mit purchase_status / residential_purchase_status und die Lieferung mit order_delivery. Beachten Sie poll_after_seconds und Retry-After. Kaufen Sie nach einem Timeout nicht mit einem neuen Idempotency-Key erneut.