# Alur integrasi

Baca katalog atau cakupan terverifikasi, tinjau harga atau revision, kirim sekali, lalu lacak operasi dan pengiriman tersimpan.

## Katalog dan pembelian

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

Pembelian multi-negara menghasilkan pesanan per negara dan satu faktur multi-baris. Diskon dihitung per negara. accepted berarti diterima antrean, bukan selesai dikirim.

## Perpanjangan

```text
renewal_options → renewal_quote → renewal → renewal_status
```

## Login tambahan

```text
extra_login_options → extra_login_create → extra_login_operation_status
```

## Daftar dan trafik Residential

```text
residential_catalog → residential_quote → residential_purchase
                                              ↓
residential_purchase_status → order_delivery → residential_package_refresh
```

## Idempotency-Key

Simpan satu Idempotency-Key untuk setiap perubahan yang dimaksud. Timeout atau HTTP 5xx bukan bukti gagal. Periksa status dengan kunci sama; jangan gunakan kunci baru untuk mengulang hasil yang belum pasti.

- [**Periksa status pembelian →****GET** `/orders/create/status`](https://docs.arnproxy.com/id/api-v1/orders/create/status)
- [**Status perpanjangan →****GET** `/renewals/status`](https://docs.arnproxy.com/id/api-v1/renewals/status)
- [**Periksa operasi login →****GET** `/extra-logins/status`](https://docs.arnproxy.com/id/api-v1/proxies/extra-logins/status)
- [**Status pengiriman Residential →****GET** `/residential/orders/status`](https://docs.arnproxy.com/id/api-v1/residential/orders/status)

---
[ARNPROXY API](https://docs.arnproxy.com/id/api-v1/workflows)

## Tujuan penggunaan: pilih subtujuan saja

Jangan meminta pelanggan memilih dua tujuan untuk pesanan standar. Temukan id=201 di catalog.purposes dan tampilkan hanya children miliknya. Pada purchase, purpose_id selalu bilangan bulat 201 dan subpurpose_id adalah ID anak yang dipilih. Struktur bertingkat dipertahankan agar integrasi lama tetap kompatibel.

Baris quote tidak memerlukan tujuan: cukup location_id, time_id, dan quantity. Tujuan wajib dikirim pada tahap 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.
```

### Tujuan “Lainnya”

Untuk Lainnya, kirim subpurpose_id=-1 serta other_purpose berisi 1–30 karakter. Pilihan lain tidak membutuhkan other_purpose. purpose_id tetap 201.

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

## Residential: paket baru dan penambahan GB

Pelanggan tidak memilih tujuan penggunaan untuk pesanan Residential. Untuk paket baru, server otomatis menetapkan tujuan tetap yang sama dengan pembelian di situs; jangan kirim purpose_id, subpurpose_id, atau other_purpose. Penambahan GB mempertahankan tujuan paket yang ada.

ID dan harga hanya contoh; gunakan nilai nyata dari katalog dan penawaran yang sama. ID JSON dan expected_total_minor harus berupa angka. Contoh sengaja memakai terms=false; kirim terms=true hanya setelah persetujuan jelas pelanggan untuk operasi berbayar.

## Satu jenis produk, dua negara

Gunakan maksimal 20 location_id berbeda dalam satu product_id. Setiap negara menjadi pesanan terpisah; checkout yang terhubung diproses dalam satu faktur. Diskon jumlah dihitung terpisah per negara.

```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
}
```

## Residential: paket baru dan penambahan GB · mode=new

Pelanggan tidak memilih tujuan penggunaan untuk pesanan Residential. Untuk paket baru, server otomatis menetapkan tujuan tetap yang sama dengan pembelian di situs; jangan kirim purpose_id, subpurpose_id, atau other_purpose. Penambahan GB mempertahankan tujuan paket yang ada.

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

## Residential: paket baru dan penambahan GB · mode=topup

Pelanggan tidak memilih tujuan penggunaan untuk pesanan Residential. Untuk paket baru, server otomatis menetapkan tujuan tetap yang sama dengan pembelian di situs; jangan kirim purpose_id, subpurpose_id, atau other_purpose. Penambahan GB mempertahankan tujuan paket yang ada.

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

## Ekspor CSV

Pilih kolom CSV dari id, endpoint, ip, port, login, dan password. Format khusus hanya menerima token %...% yang didokumentasikan dan tidak menjalankan kode. Keluaran berisi kredensial memerlukan izin credentials. Konten dikembalikan dalam JSON; aplikasi Anda menyimpannya sebagai berkas.

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

## Format koneksi khusus

Pilih kolom CSV dari id, endpoint, ip, port, login, dan password. Format khusus hanya menerima token %...% yang didokumentasikan dan tidak menjalankan kode. Keluaran berisi kredensial memerlukan izin credentials. Konten dikembalikan dalam JSON; aplikasi Anda menyimpannya sebagai berkas.

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

## Diterima bukan berarti sudah dikirim

HTTP 201/202 atau state=accepted mungkin hanya berarti permintaan diterima. Pantau operasi yang sama dengan purchase_status / residential_purchase_status dan pengiriman dengan order_delivery. Ikuti poll_after_seconds dan Retry-After. Jangan membeli ulang dengan Idempotency-Key baru setelah waktu habis.