POST /apiv2/billing/limits

Netts کی طرف سے مقرر کردہ کریڈٹ کی حد کے اندر اپنی ذاتی حدود بنائیں، تبدیل کریں، بند کریں اور فعال کریں۔ Netts کی طرف سے مقرر کردہ حدود کو ان اینڈ پوائنٹس کے ذریعے تبدیل نہیں کیا جا سکتا۔ postpaid billing کا حصہ۔

اینڈ پوائنٹس

اینڈ پوائنٹ	کام
POST /apiv2/billing/limits	اپنی حد بنائیں
PUT /apiv2/billing/limits/{id}?scope=account	اس کی قدر تبدیل کریں
POST /apiv2/billing/limits/{id}/disable?scope=account	اسے بند کریں — یہ لاگو ہونا بند ہو جاتی ہے، کچھ بھی حذف نہیں ہوتا
POST /apiv2/billing/limits/{id}/enable?scope=account	اسے دوبارہ فعال کریں

{id} حدود سے حد کی id ہے۔ تبدیلیوں کے لیے scope=account درکار ہے۔

درخواست کے ہیڈرز

ہیڈر	درکار ہے	تفصیل
X-API-KEY	ہاں	limits.write کی اجازت کے ساتھ API کی
X-Real-IP	ہاں	کی کی وائٹ لسٹ سے ایک پتہ
Idempotency-Key	ہاں	ایک منفرد سٹرنگ، 8–128 حروف، فی تبدیلی ایک
Content-Type	ہاں	application/json

Idempotency-Key دوبارہ کوشش کرنے کو محفوظ بناتی ہے۔ ایک ہی کلید اور اسی باڈی کے ساتھ درخواست دہرائیں — مثال کے طور پر ٹائم آؤٹ کے بعد — اور آپ کو اصل جواب واپس ملتا ہے؛ تبدیلی دو بار نہیں کی جاتی۔ ایک مختلف باڈی کے ساتھ اسی کلید کو 409 idempotency_conflict کے ساتھ مسترد کر دیا جاتا ہے۔

expectedRevision آپ کو ایسی تبدیلی کو اوور رائٹ کرنے سے بچاتی ہے جو آپ نے نہیں دیکھی۔ وہ revision بھیجیں جو آپ نے آخری بار پڑھی تھی (حد بناتے وقت 0)۔ اگر اس دوران حد تبدیل ہو گئی تھی، تو درخواست کو 409 revision_conflict کے ساتھ مسترد کر دیا جاتا ہے — حدود دوبارہ پڑھیں اور دوبارہ کوشش کریں۔

حد بنائیں

فیلڈ	قسم	درکار ہے	تفصیل
productCode	سٹرنگ یا null	نہیں	energy_1h، energy_5m، bandwidth، activation، aml_check؛ آپ کی مجموعی حد کے لیے null یا خارج کر دیا گیا
period	سٹرنگ	ہاں	outstanding، day، week یا order
value	سٹرنگ	ہاں	رقم، Netts کی حد کی کرنسی میں، اس سے زیادہ نہیں
expectedRevision	انٹیجر	ہاں	0

آپ ہر پراڈکٹ اور مدت کے لیے اپنی ذاتی ایک حد رکھ سکتے ہیں۔ کرنسی Netts کی حد سے لی جاتی ہے — کوئی کرنسی فیلڈ نہیں ہے۔

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

حد فوری طور پر اگلے آرڈر پر لاگو ہو جاتی ہے۔

حد تبدیل کریں

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

فیلڈ	قسم	درکار ہے	تفصیل
value	سٹرنگ	ہاں	نئی رقم، Netts کی حد سے زیادہ نہیں
expectedRevision	انٹیجر	ہاں	حد کی موجودہ revision

جواب کا فارمیٹ وہی ہے جو اوپر ہے، جس میں revision میں ایک کا اضافہ ہوتا ہے۔

حد کو بند یا فعال کریں

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

باڈی میں صرف expectedRevision ہوتا ہے۔ /enable اسی طرح کام کرتا ہے۔ بند کی گئی حد فہرست میں "enabled": false کے ساتھ رہتی ہے اور اسے بعد میں فعال کیا جا سکتا ہے؛ آپ کا قرض اور چارجز متاثر نہیں ہوتے ہیں۔

آپ کیا نہیں کر سکتے

• "origin": "netts" والی حد یا کی کی حد کو تبدیل یا بند کرنا — 403 netts_limit_readonly، یہاں تک کہ اسے کم کرنے کے لیے بھی نہیں۔
• Netts کی حد سے زیادہ قدر مقرر کرنا — 422 above_account_limit۔
• اسی پراڈکٹ اور مدت کے لیے دوسری حد بنانا — 409 limit_exists؛ اس کے بجائے موجودہ حد کو تبدیل کریں۔
• اس سے پہلے کہ Netts آپ کے اکاؤنٹ کی کریڈٹ حد مقرر کرے، حد بنانا — 409 no_account_limit۔
• ایسی حد کو فعال کرنا جس کی کرنسی موجودہ Netts کی حد سے مختلف ہو — 422 unit_mismatch؛ پہلے ایک نئی قدر مقرر کریں۔

غلطیاں

HTTP	code	معنی
400	invalid_request، invalid_amount	ایک فیلڈ غائب ہے یا اس کا فارمیٹ غلط ہے
400	idempotency_key_required، invalid_idempotency_key	کوئی Idempotency-Key نہیں، یا 8–128 حروف پر مشتمل نہیں ہے
401	-1، -2	کی غائب یا غلط ہے، یا IP وائٹ لسٹ میں شامل نہیں ہے — API گیٹ وے کی طرف سے جواب دیا گیا، دیکھیں جواب کا فارمیٹ
403	forbidden	کی کے پاس limits.write کی اجازت نہیں ہے
403	postpaid_disabled	پوسٹ پیڈ بلنگ موقوف ہے: حدود تبدیل نہیں کی جا سکتیں
403	netts_limit_readonly	حد Netts کی طرف سے مقرر کی گئی ہے
404	not_found	آپ کے اکاؤنٹ پر ایسی کوئی حد نہیں ہے
409	revision_conflict، limit_exists، idempotency_conflict، no_account_limit	اوپر دیکھیں
422	above_account_limit، product_not_postpaid، unit_mismatch	Netts کی حد سے زیادہ قدر، نامعلوم پراڈکٹ، Netts کی حد کی کرنسی تبدیل ہو گئی

تمام کوڈز پوسٹ پیڈ بلنگ میں درج ہیں۔