POST /apiv2/billing/limits

สร้าง เปลี่ยน ปิดใช้งาน และเปิดใช้งานวงเงินของคุณเองภายในวงเงินสินเชื่อที่กำหนดโดย Netts วงเงินที่กำหนดโดย Netts ไม่สามารถเปลี่ยนแปลงได้ด้วย Endpoint เหล่านี้ เป็นส่วนหนึ่งของ การเรียกเก็บเงินรายเดือน

Endpoint

Endpoint	การทำงาน
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	ใช่	คีย์ API ที่มีสิทธิ์ limits.write
X-Real-IP	ใช่	ที่อยู่จากรายการที่อนุญาต (Whitelist) ของคีย์
Idempotency-Key	ใช่	สตริงที่ไม่ซ้ำกัน ความยาว 8–128 อักขระ หนึ่งค่าต่อหนึ่งการเปลี่ยนแปลง
Content-Type	ใช่	application/json

Idempotency-Key ช่วยให้การลองส่งคำขอซ้ำมีความปลอดภัย หากส่งคำขอซ้ำด้วยคีย์เดิมและเนื้อหาคำขอเดิม เช่น หลังจากเกิดการหมดเวลา (Timeout) คุณจะได้รับผลลัพธ์เดิมกลับมา โดยจะไม่มีการดำเนินการเปลี่ยนแปลงซ้ำสอง หากใช้คีย์เดิมแต่เนื้อหาคำขอต่างออกไปจะถูกปฏิเสธด้วย 409 idempotency_conflict

expectedRevision ช่วยป้องกันไม่ให้คุณเขียนทับการเปลี่ยนแปลงที่คุณยังไม่เห็น ให้ส่งค่า revision ที่คุณอ่านล่าสุด (0 เมื่อคุณสร้างวงเงิน) หากวงเงินมีการเปลี่ยนแปลงในระหว่างนั้น คำขอจะถูกปฏิเสธด้วย 409 revision_conflict — ให้อ่าน วงเงิน อีกครั้งแล้วลองใหม่

สร้างวงเงิน

ฟิลด์	ชนิด	จำเป็น	คำอธิบาย
productCode	string หรือ null	ไม่	energy_1h, energy_5m, bandwidth, activation, aml_check; ใช้ null หรือละเว้นสำหรับวงเงินโดยรวมของคุณ
period	string	ใช่	outstanding, day, week หรือ order
value	string	ใช่	จำนวนเงิน ในสกุลเงินของวงเงิน Netts และต้องไม่สูงกว่าวงเงินดังกล่าว
expectedRevision	integer	ใช่	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	string	ใช่	จำนวนเงินใหม่ ต้องไม่สูงกว่าวงเงินของ Netts
expectedRevision	integer	ใช่	ค่า 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 มีการเปลี่ยนแปลง

รหัสทั้งหมดแสดงอยู่ใน การเรียกเก็บเงินรายเดือน