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

Schedules API

Schedules API ช่วยให้คุณสามารถสร้างและจัดการการชำระเงินแบบเป็นงวดๆ และการโอนเงินอัตโนมัติตามตารางเวลา

Endpoint ที่มี​

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

ภาพรวม​

ตารางเวลาช่วยให้การดำเนินการแบบเป็นงวดๆ เป็นไปโดยอัตโนมัติ:

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

กรณีการใช้งานที่พบบ่อย​

  • การเรียกเก็บเงินแบบสมัครสมาชิก (การเรียกเก็บเงินรายเดือน/รายปี)
  • การจ่ายเงินตามกำหนดให้กับผู้ขายในตลาด
  • การบริจาคแบบเป็นงวดๆ
  • ค่าสมาชิก
  • การชำระค่าคอมมิชชันอัตโนมัติ

วิธีการทำงานของตารางเวลา​

  1. สร้างตารางเวลาพร้อมความถี่ (รายวัน รายสัปดาห์ รายเดือน)
  2. ตารางเวลาดำเนินการโดยอัตโนมัติตามช่วงเวลาที่กำหนด
  3. แต่ละการดำเนินการจะสร้าง "occurrence"
  4. Occurrence เชื่อมโยงกับการเรียกเก็บเงินหรือการโอนเงินที่สร้างขึ้นจริง
  5. ติดตามสถานะตารางเวลาและผลลัพธ์ของ occurrence

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

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

ความถี่ของตารางเวลา​

ตารางเวลารองรับความถี่ต่อไปนี้:

ความถี่คำอธิบายตัวอย่างกรณีการใช้งาน
dailyทำงานทุกวันตามเวลาที่ระบุการจ่ายเงินรายวัน
weeklyทำงานสัปดาห์ละครั้งในวันที่ระบุการสมัครสมาชิกรายสัปดาห์
monthlyทำงานเดือนละครั้งในวันที่ระบุการเรียกเก็บเงินรายเดือน

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

ตารางเวลาจะผ่านสถานะเหล่านี้:

  1. active - ตารางเวลากำลังทำงานและจะดำเนินการตามตารางเวลา
  2. suspended - ตารางเวลาถูกหยุดชั่วคราว (สามารถเริ่มต้นใหม่ได้)
  3. deleted - ตารางเวลาถูกปิดใช้งานอย่างถาวร
  4. completed - ตารางเวลาถึงวันที่สิ้นสุดแล้ว

Occurrence​

แต่ละครั้งที่ตารางเวลาดำเนินการ จะสร้าง occurrence ขึ้นมา Occurrence มีสถานะของตัวเอง:

  • scheduled - Occurrence อยู่ในคิวรอการทำงาน
  • running - Occurrence กำลังดำเนินการอยู่
  • successful - Occurrence ดำเนินการสำเร็จ
  • failed - Occurrence ล้มเหลว (การชำระเงินถูกปฏิเสธ ยอดคงเหลือไม่เพียงพอ ฯลฯ)
  • skipped - Occurrence ถูกข้าม (เช่น ตารางเวลาถูกระงับ)

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

1. จัดการ Occurrence ที่ล้มเหลว​

ไม่ใช่การดำเนินการตามตารางเวลาทุกครั้งที่จะสำเร็จ ใช้ตัวจัดการ webhook สำหรับ:

  • schedule.occurrence.failed - จัดการการชำระเงิน/การโอนเงินที่ล้มเหลว
  • schedule.occurrence.successful - ติดตามการดำเนินการที่สำเร็จ

2. ติดตามสุขภาพของตารางเวลา​

ตรวจสอบสถานะตารางเวลาและ occurrence ล่าสุดเป็นประจำ:

  • อัตราความล้มเหลวสูงอาจบ่งชี้ปัญหาการชำระเงินของลูกค้า
  • ตารางเวลาที่ถูกระงับจะไม่ดำเนินการจนกว่าจะเปิดใช้งานใหม่

3. ตั้งค่าวันที่สิ้นสุด​

สำหรับการสมัครสมาชิกแบบมีกำหนด ให้ตั้งค่า end_date:

{
  "period": "month",
  "end_date": "2027-12-31"
}

4. ใช้ Metadata​

เก็บรายละเอียดการสมัครสมาชิกใน metadata เพื่อให้ค้นหาได้ง่าย:

{
  "metadata": {
    "plan": "premium",
    "customer_id": "cust_123",
    "subscription_id": "sub_456"
  }
}

ข้อจำกัด​

  • ช่วงเวลาตารางเวลาขั้นต่ำ: 1 วัน
  • จำนวนตารางเวลาที่ใช้งานสูงสุดต่อบัญชี: ติดต่อฝ่ายสนับสนุนสำหรับข้อจำกัด
  • ตารางเวลาไม่สามารถแก้ไขได้หลังจากสร้าง (ต้องลบและสร้างใหม่)
  • Occurrence ที่ล้มเหลวจะไม่ถูกลองใหม่โดยอัตโนมัติ

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

ข้อผิดพลาดที่พบบ่อยเมื่อทำงานกับตารางเวลา:

รหัสข้อผิดพลาดคำอธิบายวิธีแก้ไข
invalid_frequencyค่า period ไม่ถูกต้องใช้ daily, weekly หรือ monthly
invalid_start_dateวันที่เริ่มต้นอยู่ในอดีตใช้วันที่ในอนาคต
insufficient_balanceยอดคงเหลือไม่เพียงพอสำหรับการโอนเพิ่มเงินก่อนที่ตารางเวลาจะทำงาน
invalid_recipientไม่พบผู้รับหรือไม่ได้ใช้งานตรวจสอบว่าผู้รับมีอยู่จริง

ทรัพยากรที่เกี่ยวข้อง​