ข้ามไปยังเนื้อหาหลัก
เวอร์ชัน: ล่าสุด

Charge Schedules API

Charge Schedules API ช่วยให้คุณสร้างและจัดการกำหนดการเรียกเก็บเงินแบบเป็นกลุ่ม API นี้ออกแบบมาสำหรับการดำเนินการปริมาณมาก ทำให้คุณสามารถอัปโหลดไฟล์ CSV เพื่อสร้างหลายกำหนดการพร้อมกัน และจัดการกำหนดการที่มีอยู่ผ่านการหยุดชั่วคราว เปิดใช้งานต่อ และลบแบบกลุ่ม

Endpoint ที่ใช้งานได้​

Endpoint ที่เกี่ยวข้อง​

ภาพรวม​

Charge Schedules API มีการดำเนินการแบบกลุ่มสำหรับจัดการการเรียกเก็บเงินแบบเป็นงวด:

  • อัปโหลด CSV - สร้างกำหนดการเรียกเก็บเงินหลายร้อยหรือหลายพันรายการจากไฟล์ CSV เดียว
  • ตรวจสอบความคืบหน้า - ติดตามสถานะของงานสร้างแบบกลุ่มแบบเรียลไทม์
  • รายงานสถานะ - ดาวน์โหลดรายงานละเอียดพร้อมสถานะสำเร็จ/ล้มเหลวของแต่ละกำหนดการ
  • หยุดชั่วคราวแบบกลุ่ม - หยุดกำหนดการที่ใช้งานอยู่หลายรายการพร้อมกัน
  • เปิดใช้งานต่อแบบกลุ่ม - เปิดใช้งานกำหนดการที่หยุดชั่วคราวหลายรายการพร้อมกัน
  • ลบแบบกลุ่ม - ลบกำหนดการหลายรายการถาวรในการดำเนินการครั้งเดียว

กรณีการใช้งานทั่วไป​

  • ย้ายลูกค้าสมาชิกจากแพลตฟอร์มอื่น
  • ตั้งค่าการชำระเงินแบบเป็นงวดสำหรับฐานลูกค้าจำนวนมาก
  • การจัดการกำหนดการตามฤดูกาล (หยุดชั่วคราว/เปิดใช้งานต่อสำหรับวันหยุด)
  • ยกเลิกกำหนดการแบบกลุ่มสำหรับลูกค้าที่ยกเลิกบริการ
  • ตั้งค่าการเรียกเก็บเงินแบบเป็นงวดเริ่มต้นสำหรับลูกค้าองค์กร

วิธีการทำงานของการสร้างแบบกลุ่ม​

  1. เตรียมไฟล์ CSV พร้อมข้อมูลลูกค้าและกำหนดการ
  2. อัปโหลดไฟล์ CSV เพื่อสร้างงานสร้างแบบกลุ่ม
  3. ตรวจสอบความคืบหน้าของงานโดยใช้ recurring_id
  4. ดาวน์โหลดรายงานสถานะเพื่อตรวจสอบผลลัพธ์และจัดการข้อผิดพลาด
  5. กำหนดการที่สร้างสำเร็จจะเริ่มทำงานโดยอัตโนมัติ

รูปแบบไฟล์ CSV​

เมื่อสร้างกำหนดการแบบกลุ่ม ไฟล์ CSV ของคุณต้องมีคอลัมน์ต่อไปนี้:

คอลัมน์จำเป็นคำอธิบาย
customer_keyใช่ตัวระบุเฉพาะสำหรับแถวลูกค้า (สำหรับการติดตาม)
customerใช่Customer ID (cust_*) ที่มีบัตรแนบอยู่
cardไม่Card ID เฉพาะที่จะเรียกเก็บเงิน (ใช้ค่าเริ่มต้นถ้าไม่ระบุ)
amountใช่จำนวนเงินที่เรียกเก็บในหน่วยสกุลเงินที่เล็กที่สุด
descriptionไม่คำอธิบายสำหรับแต่ละการเรียกเก็บเงิน
everyใช่ตัวคูณความถี่ (เช่น 1 สำหรับทุกเดือน)
periodใช่หน่วยเวลา: day, week, หรือ month
days_of_monthตามเงื่อนไขวันที่จะเรียกเก็บเงิน (จำเป็นสำหรับ period รายเดือน)
start_dateไม่วันที่เริ่มต้นกำหนดการ (YYYY-MM-DD)
end_dateไม่วันที่สิ้นสุดกำหนดการ (YYYY-MM-DD)

ตัวอย่าง CSV​

customer_key,customer,card,amount,description,every,period,days_of_month,start_date,end_date
sub_001,cust_test_abc123,,100000,Monthly premium plan,1,month,1,2025-02-01,2026-01-31
sub_002,cust_test_def456,card_test_xyz789,50000,Basic subscription,1,month,15,2025-02-01,
sub_003,cust_test_ghi012,,200000,Enterprise plan,1,month,1;15,2025-02-01,2025-12-31

การยืนยันตัวตน​

Endpoint ทั้งหมดของ Charge Schedules API ต้องใช้การยืนยันตัวตนด้วย secret key ของคุณ

ขีดจำกัดการดำเนินการแบบกลุ่ม​

การดำเนินการขีดจำกัด
ขนาดไฟล์ CSVสูงสุด 10MB
กำหนดการต่อ CSVสูงสุด 10,000 แถว
Schedule IDs ต่อการหยุดชั่วคราว/เปิดใช้งานต่อ/ลบแบบกลุ่มสูงสุด 100 IDs
งานสร้างแบบกลุ่มพร้อมกัน5 ต่อบัญชี

วงจรชีวิตสถานะงาน​

งานสร้างแบบกลุ่มดำเนินผ่านสถานะเหล่านี้:

  1. pending - งานอยู่ในคิวและรอเริ่มต้น
  2. processing - งานกำลังสร้างกำหนดการอย่างจริงจัง
  3. completed - งานเสร็จสิ้น (ตรวจสอบรายงานสำหรับผลลัพธ์แต่ละรายการ)
  4. failed - งานพบข้อผิดพลาดร้ายแรง

การจัดการข้อผิดพลาด​

ข้อผิดพลาดการสร้างแบบกลุ่ม​

งานสร้างแบบกลุ่มออกแบบมาให้มีความทนทาน หากแถวบางแถวล้มเหลว:

  • งานจะดำเนินการแถวที่เหลือต่อไป
  • แถวที่ล้มเหลวจะถูกบันทึกในรายงานสถานะ
  • ดาวน์โหลดรายงานเพื่อดูข้อความข้อผิดพลาดเฉพาะต่อแถว

ข้อผิดพลาด CSV ทั่วไป​

ข้อผิดพลาดคำอธิบายการแก้ไข
invalid_customerไม่พบ Customer IDตรวจสอบว่าลูกค้ามีอยู่และมีบัตรแนบอยู่
invalid_cardไม่พบบัตรหรือบัตรหมดอายุใช้ Card ID ที่ถูกต้องหรือลบออกเพื่อใช้ค่าเริ่มต้น
invalid_amountจำนวนเงินเป็นศูนย์หรือติดลบระบุจำนวนเงินที่เป็นจำนวนเต็มบวก
invalid_periodค่า period ไม่ถูกต้องใช้ day, week, หรือ month
missing_days_of_monthจำเป็นสำหรับ period รายเดือนระบุวัน (เช่น 1 หรือ 1;15)

ข้อผิดพลาดการหยุดชั่วคราว/เปิดใช้งานต่อ/ลบแบบกลุ่ม​

ข้อผิดพลาดคำอธิบายการแก้ไข
schedule_not_foundSchedule IDs หนึ่งรายการขึ้นไปไม่ถูกต้องตรวจสอบว่า Schedule IDs ทั้งหมดมีอยู่
invalid_statusกำหนดการอยู่ในสถานะที่ไม่ถูกต้องสำหรับการดำเนินการตรวจสอบสถานะกำหนดการปัจจุบัน
too_many_idsเกินจำนวน IDs สูงสุดต่อคำขอแบ่งเป็นหลายคำขอ (สูงสุด 100)

แนวทางปฏิบัติที่ดี​

1. ตรวจสอบ CSV ก่อนอัปโหลด​

ตรวจสอบไฟล์ CSV ของคุณสำหรับ:

  • หัวคอลัมน์ที่ถูกต้อง
  • Customer IDs ที่ถูกต้อง
  • รูปแบบวันที่ที่ถูกต้อง (YYYY-MM-DD)
  • ค่าจำนวนเงินเป็นจำนวนเต็ม (ไม่ใช่ทศนิยม)

2. ตรวจสอบความคืบหน้าของงาน​

เรียก endpoint ตรวจสอบเป็นระยะ:

// ตรวจสอบทุก 5 วินาทีจนกว่าจะเสร็จ
const checkStatus = async (recurringId) => {
  const status = await getJobStatus(recurringId);
  if (status.state === 'completed') {
    return await downloadReport(recurringId);
  }
  setTimeout(() => checkStatus(recurringId), 5000);
};

3. จัดการความล้มเหลวบางส่วน​

ดาวน์โหลดและตรวจสอบรายงานสถานะเสมอ:

  • ลองแถวที่ล้มเหลวใหม่แต่ละรายการหรือใน CSV ใหม่
  • บันทึกข้อผิดพลาดสำหรับการตรวจสอบ
  • แจ้งลูกค้าที่ได้รับผลกระทบหากจำเป็น

4. ใช้ Customer Keys ที่ไม่ซ้ำกัน​

รวมค่า customer_key ที่มีความหมายเพื่อระบุแถวในรายงานสถานะได้ง่ายและจับคู่ผลลัพธ์กลับไปยังระบบของคุณ

แหล่งข้อมูลที่เกี่ยวข้อง​