การตรวจสอบยอดเงินผ่าน API ก่อนเริ่มสั่งซื้อจำนวนมาก

ทำไมต้องขอยอดเงินก่อนเริ่มคิว

การสั่งซื้อจำนวนมากโดยไม่ตรวจสอบยอดเงินล่าสุดทำให้เกิดการปฏิเสธบางส่วน: คำสั่งแรก ๆ ถูกสร้างขึ้น แต่คำสั่งถัดไปได้รับข้อผิดพลาดเรื่องเงินไม่พอ สถานการณ์นี้ยุ่งยากที่สุดเมื่อส่งพร้อมกัน ใช้บริการต่างกัน และมีหลายโปรเซสทำงานกับบัญชีเดียวกัน

สิ่งที่สำคัญสำหรับการเริ่มทำงานไม่ใช่ยอดเติมเงินรวมหรือยอดคงเหลือทางบัญชีในหน้าผู้ใช้ แต่เป็นจำนวนเงินที่บริการอนุญาตให้หักได้ในขณะสร้างคำสั่งซื้อใหม่ เงินสำหรับคำสั่งที่ยังใช้งานอยู่อาจถูกกันไว้ในยอดสำรองแล้ว แม้ว่าการหักเงินครั้งสุดท้ายยังไม่ปรากฏในประวัติธุรกรรม

เปรียบเทียบงบประมาณของคิวกับฟิลด์ยอดคงเหลือที่ใช้ได้ ไม่ใช่กับยอดรวมในบัญชี

การตอบกลับของเมธอดยอดเงินมีหน้าตาอย่างไร

ชื่อฟิลด์กำหนดโดยเอกสารของแต่ละแพลตฟอร์ม แต่สัญญาของเมธอดยอดเงินที่ใช้งานสะดวกมักคืนค่า total, available, reserved, currency และ updated_at ด้านล่างเป็นตัวอย่างโครงสร้างที่ใช้เป็นแนวทางในการเชื่อมต่อได้ นี่ไม่ใช่การตอบกลับสากลสำหรับทุกบริการ แต่เป็นตัวอย่างรูปแบบข้อมูลที่เข้าใจง่าย

คำขออาจมีหน้าตาดังนี้:

curl -X GET "https://api.example.com/v1/balance" \
-H "Authorization: Bearer API_TOKEN" \
-H "Accept: application/json"

การตอบกลับ:

{
"total": "125.80",
"available": "84.50",
"reserved": "41.30",
"currency": "USD",
"updated_at": "2025-01-15T10:42:18Z"
}

ในตัวอย่างนี้ total คือเงินทั้งหมดของบัญชี available คือเงินสำหรับคำสั่งซื้อใหม่ reserved คือจำนวนเงินสำหรับรายการที่สร้างไว้ก่อนหน้า การตรวจสอบสอดคล้องกัน: 125.80 ลบ 41.30 เท่ากับ 84.50 ฟิลด์ currency กำหนดหน่วยในการคำนวณ และ updated_at ช่วยให้เข้าใจว่าข้อมูลใหม่แค่ไหน

วิธีแยกวิเคราะห์ available และ reserved

ฟิลด์ available ใช้ตัดสินใจเรื่องการเริ่มทำงาน หากคิวมีมูลค่า 80.00 และ available เท่ากับ 84.50 เงินเพียงพอเฉพาะในเงื่อนไขที่ API จะไม่เพิ่มค่าธรรมเนียมแยกต่างหากหรือไม่คำนวณราคาใหม่ในขณะสร้างคำสั่ง ฟิลด์ reserved ไม่ได้บวกเข้ากับยอดคงเหลือที่ใช้ได้ เพราะจำนวนนี้ถูกใช้ไปแล้ว

reserved อาจรวมค่าของคำสั่งที่มีสถานะ processing, pending หรือ review — ชุดที่แน่นอนขึ้นอยู่กับกฎของแพลตฟอร์ม บางครั้งยอดสำรองถูกปลดปล่อยหลังการยกเลิก การทำบางส่วนเสร็จ หรือการตรวจสอบด้วยมือ ดังนั้นการคำนวณด้วยตัวเองจากรายการคำสั่งซื้อทำได้เพียงเป็นการตรวจสอบเพิ่มเติมเท่านั้น

• total เหมาะสำหรับตรวจสอบกับประวัติการเติมเงินและการหักเงิน;
• available เหมาะสำหรับอนุญาตให้คิวใหม่เริ่มทำงาน;
• reserved แสดงว่าเงินถูกบล็อกไว้สำหรับรายการที่ใช้งานอยู่แล้วเท่าไร;
• currency ละเลยไม่ได้แม้จะทำงานกับบัญชีเดียว;
• updated_at มีประโยชน์สำหรับบันทึกและวินิจฉัยการตอบกลับที่ล้าสมัย

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

ตรวจสอบรูปแบบจำนวนเงินในเอกสาร API

ในตัวอย่าง จำนวนเงินถูกส่งเป็นสตริง: "84.50" ไม่ใช่ตัวเลข 84.5 รูปแบบนี้รักษาค่าที่แน่นอนที่บริการส่งกลับมา หาก API ใช้สตริงที่มีจุดทศนิยม ไม่ควรแปลงเป็นตัวเลขทศนิยมทันทีและเปรียบเทียบด้วย float

ตัวอย่างเช่น การคำนวณของคุณอาจได้ 84.499999 แทนที่จะเป็น 84.50 ที่คาดไว้ ที่ขอบของงบประมาณ สิ่งนี้อาจทำให้คิวผ่านผิดพลาดหรือหยุดคิวโดยไม่จำเป็น สำหรับการดำเนินการกับค่าทศนิยมแบบสตริง ให้ใช้ชนิดข้อมูลทศนิยมที่รองรับความแม่นยำของเศษส่วนคงที่

สัญญาที่พบบ่อยอีกแบบคือหน่วยย่อยขั้นต่ำที่เป็นจำนวนเต็ม ในกรณีนี้การตอบกลับอาจมี "available_minor": 8450 และ "currency": "USD" ส่วนราคาคำสั่งคือ "price_minor": 1250 ภายใน API เช่นนี้ 8450 หมายถึง 84.50 หากกฎของสกุลเงินกำหนดตำแหน่งทศนิยมสองตำแหน่ง การหารค่าด้วย 100 ทำได้เฉพาะเมื่อเอกสารระบุไว้อย่างชัดเจนเท่านั้น

อย่าผสมสกุลเงินและรูปแบบราคา

ก่อนคำนวณคิว ให้เปรียบเทียบ currency จากยอดเงินกับสกุลเงินของเมธอดราคาหรือการตอบกลับขณะสร้างคำสั่งซื้อ หากยอดเงินคืนค่าสกุลเงินหนึ่ง แต่แคตตาล็อกบริการเป็นอีกสกุลเงินหนึ่ง จะนำตัวเลขมาใส่กันโดยตรงไม่ได้ ต้องใช้การคำนวณที่แพลตฟอร์มให้มาเอง หรือเมธอดแปลงสกุลเงินที่ยืนยันแยกต่างหาก

การแปลงล่วงหน้าฝั่งคุณสะดวกสำหรับการวางแผน แต่มีข้อเสีย: บริการอาจใช้อัตราแลกเปลี่ยน ค่าธรรมเนียม หรือกฎการปัดเศษที่แตกต่างในขณะหักเงิน ปลอดภัยกว่าคือส่งคำสั่งซื้อด้วยพารามิเตอร์ที่ API คืนต้นทุนสุดท้ายในสกุลเงินของยอดคงเหลือ หรือขอคำนวณราคาก่อนสร้างโดยตรง

หากเมธอดราคาตอบกลับ "price": "12.345" แต่ยอดเงินเก็บค่าด้วยทศนิยมสองตำแหน่ง ให้ตรวจสอบกฎการปัดเศษ อย่าปัดลงโดยอัตโนมัติ เพราะการหักเงินจริงอาจสูงกว่า สำหรับการอนุญาตคิว ให้ใช้จำนวนเงินที่ API เรียกว่าต้นทุนสุดท้ายของคำสั่งซื้อเท่านั้น

คำนวณงบประมาณของคิวก่อนคำขอแรก

ก่อนเริ่มทำงาน ให้รวบรวมคำสั่งทั้งหมดและคำนวณต้นทุนโดยคำนึงถึงปริมาณ บริการที่เลือก ภูมิภาค ตัวเลือกเพิ่มเติม และค่าธรรมเนียมหากส่งแยกต่างหาก อย่าเปรียบเทียบ available กับราคาพื้นฐานจากอินเทอร์เฟซ: ใน API ยอดรวมอาจขึ้นอยู่กับพารามิเตอร์ของคำสั่งซื้อนั้น ๆ

สมมติว่าในคิวมีสามคำสั่ง API คำนวณราคาคืนค่า 18.40, 27.15 และ 31.60 ในสกุลเงินเดียวกับที่ระบุใน balance.currency งบประมาณเท่ากับ 77.15 หาก balance.available เท่ากับ 84.50 หลังเริ่มทำงานตามแผนจะเหลือ 7.35 หาก available เท่ากับ 76.90 จะเริ่มทั้งคิวไม่ได้

1. ดึงราคาตามพารามิเตอร์จริงของแต่ละคำสั่งซื้อ
2. รวมต้นทุนสุดท้ายโดยไม่เปลี่ยนรูปแบบและสกุลเงิน
3. เปรียบเทียบงบประมาณกับ available จากการตอบกลับยอดเงินล่าสุด
4. เมื่อยอดคงเหลือเพียงพอ ให้บันทึกจำนวนเงินเป็นยอดสำรองการเริ่มทำงานภายในเครื่อง
5. หลังสร้างแต่ละคำสั่ง ให้ลดยอดสำรองภายในเครื่องตามต้นทุนที่ยืนยันแล้ว

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

ตรวจสอบครั้งที่สองก่อนส่งจริง

ยอดเงินที่ได้ตอนเตรียมแคมเปญจะล้าสมัยอย่างรวดเร็ว ในช่วงเวลาระหว่างการคำนวณและการเริ่มทำงาน ผู้ปฏิบัติงานคนอื่น ระบบอัตโนมัติ หรือคำสั่งที่ใช้งานอยู่อาจเปลี่ยน available และ reserved ต้องส่งคำขอซ้ำหลังสร้างคิวเสร็จและก่อนคำสั่งแรกโดยตรง

ขั้นตอนการทำงานประกอบด้วยสองช่วง: ก่อนอื่นดึงราคาและประเมินงบประมาณ จากนั้นขอยอด balance อีกครั้ง หากค่า available ลดลงและต่ำกว่าจำนวนที่คำนวณไว้ จะไม่ส่งทั้งคิว ระหว่างการตรวจสอบครั้งสุดท้ายและการเริ่มทำงาน ไม่ควรทำการหักเงินอื่นจากบัญชีเดียวกัน

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

วิธีเริ่มคิวเมื่อเงินไม่พอ

หาก available น้อยกว่างบประมาณ อย่าส่งคำขอทั้งหมดโดยหวังว่าบางส่วนจะผ่าน ให้แบ่งคิวเป็นแพ็กเกจที่มีต้นทุนอยู่ในวงเงินที่ใช้ได้ ในตัวอย่างที่มียอดคงเหลือ 76.90 สามารถส่งสองคำสั่งแรกด้วยมูลค่า 45.55 แล้วหยุด: คำสั่งที่สามที่ 31.60 ต้องตรวจสอบซ้ำ

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

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

หลังแต่ละแพ็กเกจ ให้ยึดตามการตอบกลับใหม่ของ API ไม่ใช่เพียงการหักลบภายในเครื่องจากยอดเงินเดิม การคำนวณภายในเครื่องมีประโยชน์สำหรับการควบคุม แต่ไม่เห็นการคืนเงิน การหักเงินภายนอก และการคำนวณยอดสำรองใหม่

ปกป้องงบประมาณเมื่อส่งพร้อมกัน

ในการประมวลผลแบบลำดับ เพียงลดวงเงินภายในเครื่องหลังยืนยันคำสั่งซื้อก็เพียงพอ ในรูปแบบขนาน ผู้ปฏิบัติงานสองรายอาจเห็น available 84.50 พร้อมกันและแต่ละรายวางแผนใช้จ่าย 60.00 การตัดสินใจทั้งสองดูเหมือนยอมรับได้แยกกัน แต่รวมกันแล้วเกินยอดคงเหลือที่ใช้ได้

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

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

หากโปรเซสสิ้นสุดก่อนได้รับการตอบกลับ จะถือว่ายอดสำรองภายในเครื่องถูกใช้ไปแล้วหรือว่างทันทีไม่ได้ ก่อนอื่นให้ตรวจสอบว่าคำสั่งซื้อถูกสร้างขึ้นหรือไม่ โดยใช้ตัวระบุภายนอกหรือเมธอดค้นหารายการ

ใช้ยอดสำรองของ API หากมีให้ใช้

API บางตัวอนุญาตให้สร้างยอดสำรองสำหรับชุดรายการ หรือดำเนินการคำสั่งซื้อในสองขั้นตอน: คำนวณ บล็อกจำนวนเงิน ยืนยัน ในรูปแบบนี้ ช่วงเวลาระหว่างการตรวจสอบและการหักเงินจะแคบลง ซึ่งโปรเซสอื่นสามารถใช้เงินของบัญชีได้

เมื่อมีเมธอดดังกล่าว ให้บันทึกตัวระบุยอดสำรอง จำนวนเงิน สกุลเงิน อายุการใช้งาน และสถานะ จากนั้นส่งตัวระบุนี้เมื่อสร้างคำสั่งซื้อ หากสัญญาของ API กำหนดให้ทำเช่นนั้น หลังคิวเสร็จสิ้น ให้ตรวจสอบส่วนที่ไม่ได้ใช้และข้อเท็จจริงของการปลดบล็อก

ยอดสำรองของ API ไม่ได้แก้ปัญหาทั้งหมด: อาจมีอายุการใช้งานสั้น ไม่ครอบคลุมค่าธรรมเนียม หรือถูกปลดปล่อยหลังเกิดข้อผิดพลาดในการยืนยัน การสำรองภายในเครื่องนำไปใช้ง่ายกว่า แต่มีข้อเสียคือไม่ป้องกันการใช้จ่ายที่สร้างขึ้นนอกแอปพลิเคชันของคุณ

แยกข้อผิดพลาดของยอดเงินออกจากยอดคงเหลือศูนย์

การตอบกลับที่มีรหัสข้อผิดพลาด การหมดเวลา หรือการจำกัดความถี่ของคำขอ ไม่ได้หมายความว่า available เท่ากับศูนย์ อย่าใส่ค่าล่าสุดที่ทราบโดยอัตโนมัติหากการเริ่มทำงานขนาดใหญ่ขึ้นอยู่กับค่านั้น เมื่อไม่สามารถดึงยอดเงินล่าสุดได้ ต้องหยุดคิวชั่วคราว

จัดการการปฏิเสธขณะสร้างคำสั่งซื้อแยกต่างหาก อาจเกี่ยวข้องกับเงินไม่พอ แต่ก็อาจเกิดจากตัวระบุบริการไม่ถูกต้อง ปริมาณที่ไม่ได้รับอนุญาต ข้อจำกัดของช่องทาง หรือการทำรายการเดิมซ้ำ ให้บันทึกรหัสและข้อความข้อผิดพลาดพร้อมกับตัวระบุภายนอกของคำสั่ง

• เมื่อเกิดข้อผิดพลาดการอนุญาต ให้รีเฟรชการเข้าถึงแล้วจึงส่งคำขอซ้ำ
• เมื่อถึงขีดจำกัดคำขอ ให้หยุดพักตามกฎของ API
• เมื่อสร้างคำสั่งซื้อหมดเวลา ก่อนอื่นให้ตรวจสอบว่ารายการปรากฏขึ้นจริงหรือไม่
• เมื่อเกิดข้อผิดพลาดเงินไม่พอ ให้หยุดแพ็กเกจและขอยอด balance ใหม่

อย่าสร้างรายการซ้ำหลังหมดเวลา

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

ส่งตัวระบุภายนอกที่ไม่ซ้ำกันของคำสั่งซื้อ หาก API รองรับฟิลด์ client_order_id, external_id หรือ idempotency_key บันทึกไว้ก่อนส่งคำขอ หลังหมดเวลา ให้ค้นหารายการด้วยค่านี้ หรือขอสถานะด้วยตัวระบุที่ได้รับก่อนหน้า

การส่งซ้ำโดยไม่ตรวจสอบเร็วกว่า แต่ข้อเสียตรงไปตรงมา: อาจมีคำสั่งซื้อซ้ำ การสำรองเงินซ้ำ และความคลาดเคลื่อนระหว่างการคำนวณงบประมาณของคุณกับการหักเงินจริง

สิ่งที่ควรบันทึกในบันทึกการเริ่มทำงาน

บันทึกช่วยฟื้นคืนขั้นตอนของการดำเนินการจำนวนมากและอธิบายว่าทำไมแพ็กเกจหนึ่งจึงหยุด สำหรับการเริ่มทำงานแต่ละครั้ง ให้บันทึกเวลาของการตรวจสอบสองครั้ง total, available, reserved, currency งบประมาณที่คำนวณ ขนาดของยอดสำรองภายในเครื่อง และรายการตัวระบุภายนอกของคำสั่ง

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

การบันทึกแบบเต็มมีประโยชน์ในการดีบัก แต่มีข้อเสีย: หากไม่กรอง ข้อมูลการเข้าถึงและข้อมูลลูกค้าอาจเข้าไปในที่จัดเก็บ

ทดสอบขั้นตอนกับคิวขนาดเล็ก

ก่อนการเริ่มทำงานขนาดใหญ่ ให้ทำสถานการณ์สั้น ๆ: ขอยอด balance ขอราคาสุดท้าย สร้างแพ็กเกจจำกัด ขอยอด balance อีกครั้ง และเปรียบเทียบการเปลี่ยนแปลงที่คาดไว้ของ available และ reserved กับการตอบกลับจริง วิธีนี้ช่วยสังเกตได้ว่าบริการสำรองเงินเมื่อใดและหักเงินอย่างสมบูรณ์เมื่อใด

แพ็กเกจทดสอบไม่รับประกันพฤติกรรมเดียวกันภายใต้ภาระหนัก: อาจถึงขีดจำกัด โปรเซสขนาน หรือข้อจำกัดของบริการเฉพาะ ดังนั้นในคิวขนาดใหญ่ ให้แบ่งการเริ่มทำงานเป็นแพ็กเกจต่อไป ตรวจสอบยอดคงเหลือที่ใช้ได้ระหว่างแพ็กเกจ และวิเคราะห์การปฏิเสธแต่ละครั้งแยกกัน