POST /apiv2/billing/limits

Buat, ubah, nonaktifkan, dan aktifkan limit Anda sendiri di dalam batas kredit yang ditetapkan oleh Netts. Limit yang ditetapkan oleh Netts tidak dapat diubah menggunakan endpoint ini. Bagian dari penagihan pascabayar.

Endpoint

Endpoint	Fungsi
POST /apiv2/billing/limits	membuat limit Anda sendiri
PUT /apiv2/billing/limits/{id}?scope=account	mengubah nilainya
POST /apiv2/billing/limits/{id}/disable?scope=account	menonaktifkannya — limit berhenti berlaku, tidak ada yang dihapus
POST /apiv2/billing/limits/{id}/enable?scope=account	mengaktifkannya kembali

{id} adalah id limit dari limit. scope=account wajib disertakan untuk perubahan.

Header Permintaan

Header	Wajib	Deskripsi
X-API-KEY	ya	API key dengan izin limits.write
X-Real-IP	ya	Alamat dari whitelist key
Idempotency-Key	ya	string unik, 8–128 karakter, satu per perubahan
Content-Type	ya	application/json

Idempotency-Key membuat percobaan ulang (retry) aman. Ulangi permintaan dengan key yang sama dan body yang sama — misalnya setelah waktu habis (timeout) — dan Anda akan menerima kembali respons awal; perubahan tidak akan dilakukan dua kali. Key yang sama dengan body yang berbeda akan ditolak dengan 409 idempotency_conflict.

expectedRevision melindungi Anda dari menimpa perubahan yang belum Anda lihat. Kirimkan revision terakhir yang Anda baca (0 saat Anda membuat limit). Jika limit telah berubah sementara itu, permintaan ditolak dengan 409 revision_conflict — baca kembali limit dan coba lagi.

Buat limit

Bidang	Tipe	Wajib	Deskripsi
productCode	string atau null	tidak	energy_1h, energy_5m, bandwidth, activation, aml_check; null atau diabaikan untuk limit keseluruhan Anda
period	string	ya	outstanding, day, week atau order
value	string	ya	jumlah, dalam mata uang limit Netts, tidak boleh lebih tinggi darinya
expectedRevision	integer	ya	0

Anda dapat memiliki satu limit milik Anda sendiri untuk setiap produk dan periode. Mata uang diambil dari limit Netts — tidak ada bidang mata uang.

curl -s -X POST 'https://netts.io/apiv2/billing/limits' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-Real-IP: 203.0.113.10' \
  -H 'Idempotency-Key: 6f1c2b8e-limit-5m-day' \
  -H 'Content-Type: application/json' \
  -d '{"productCode": "energy_5m", "period": "day", "value": "200", "expectedRevision": 0}'

{
  "success": true,
  "data": {
    "id": 5,
    "scope": "account",
    "origin": "client",
    "productCode": "energy_5m",
    "period": "day",
    "enabled": true,
    "limit": { "unit": "USD", "value": "200.000000" },
    "equivalent": { "unit": "TRX", "value": "604.514867" },
    "revision": 1,
    "fx": { "usdPerTrx": "0.33084276", "at": "2026-10-19T20:24:23.449930+00:00" },
    "fxStatus": "ok"
  },
  "timestamp": "2026-10-19T20:30:02+00:00"
}

Limit langsung berlaku untuk pesanan berikutnya.

Ubah limit

curl -s -X PUT 'https://netts.io/apiv2/billing/limits/5?scope=account' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-Real-IP: 203.0.113.10' \
  -H 'Idempotency-Key: 6f1c2b8e-limit-5m-300' \
  -H 'Content-Type: application/json' \
  -d '{"value": "300", "expectedRevision": 1}'

Bidang	Tipe	Wajib	Deskripsi
value	string	ya	jumlah baru, tidak boleh lebih tinggi dari limit Netts
expectedRevision	integer	ya	revision saat ini dari limit tersebut

Respons memiliki format yang sama seperti di atas, dengan revision bertambah satu.

Nonaktifkan atau aktifkan limit

curl -s -X POST 'https://netts.io/apiv2/billing/limits/5/disable?scope=account' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-Real-IP: 203.0.113.10' \
  -H 'Idempotency-Key: 6f1c2b8e-limit-5m-off' \
  -H 'Content-Type: application/json' \
  -d '{"expectedRevision": 2}'

Body hanya berisi expectedRevision. /enable bekerja dengan cara yang sama. Limit yang dinonaktifkan tetap berada di dalam daftar dengan "enabled": false dan dapat diaktifkan kembali nanti; utang dan tagihan Anda tidak terpengaruh.

Yang tidak dapat Anda lakukan

• Mengubah atau menonaktifkan limit dengan "origin": "netts" atau limit key — 403 netts_limit_readonly, bahkan untuk menurunkannya.
• Menetapkan nilai yang lebih tinggi dari limit Netts — 422 above_account_limit.
• Membuat limit kedua untuk produk dan periode yang sama — 409 limit_exists; ubah limit yang sudah ada sebagai gantinya.
• Membuat limit sebelum Netts menetapkan batas kredit akun Anda — 409 no_account_limit.
• Mengaktifkan limit yang mata uangnya berbeda dari limit Netts saat ini — 422 unit_mismatch; tetapkan nilai baru terlebih dahulu.

Respons Error

HTTP	code	Arti
400	invalid_request, invalid_amount	suatu bidang hilang atau memiliki format yang salah
400	idempotency_key_required, invalid_idempotency_key	tidak ada Idempotency-Key, atau panjangnya bukan 8–128 karakter
401	-1, -2	key hilang atau tidak valid, atau IP tidak masuk whitelist — dijawab oleh API gateway, lihat format respons
403	forbidden	key tidak memiliki izin limits.write
403	postpaid_disabled	penagihan pascabayar dijeda: limit tidak dapat diubah
403	netts_limit_readonly	limit ditetapkan oleh Netts
404	not_found	tidak ada limit seperti itu di akun Anda
409	revision_conflict, limit_exists, idempotency_conflict, no_account_limit	lihat di atas
422	above_account_limit, product_not_postpaid, unit_mismatch	nilai di atas limit Netts, produk tidak dikenal, mata uang limit Netts berubah

Semua kode tercantum dalam penagihan pascabayar.