การจัดการสถานะ «กำลังดำเนินการ» เมื่อตรวจสอบคำสั่งซื้อผ่าน API

processing ในคำตอบ API หมายถึงอะไร

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

Processing ไม่ได้ยืนยันว่าดำเนินการสำเร็จ และไม่ได้หมายถึงข้อผิดพลาด หลังจากนั้นคำสั่งซื้ออาจเปลี่ยนเป็น completed, partial, canceled หรือ failed ตราบใดที่ผู้ให้บริการยังส่งสถานะ промежуточный อย่าสร้างคำขอใหม่สำหรับลิงก์เดิมและปริมาณเดิม

HTTP 200 พร้อมสถานะ processing หมายถึงการตอบกลับ API สำเร็จ ไม่ใช่การเสร็จสิ้นคำสั่งซื้อสำเร็จ เหตุการณ์ทั้งสองนี้ต้องจัดเก็บและจัดการแยกจากกัน

ต้องใช้ข้อมูลอะไรในการตรวจสอบคำสั่งซื้อ

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

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

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

ตัวอย่างการเรียกสถานะด้วย curl

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

คำขอ GET สำหรับคำสั่งซื้อเดียว

curl -X GET "https:///orders//status" \

-H "Authorization: Bearer " \

-H "Accept: application/json"

ตัวอย่างการตอบกลับ:

{

"order_id": "",

"status": "processing",

"completed_quantity": 250,

"remains": 750,

"updated_at": "значение_времени"

}

ฟิลด์ completed_quantity และ remains แสดงเป็นเพียงตัวอย่างโครงสร้างเท่านั้น ผู้ให้บริการอาจใช้ progress, start_count, balance หรือชื่ออื่น ข้อเสียของวิธี GET คือ API บางรายรับการตรวจสอบสถานะผ่าน POST เท่านั้น

ตัวอย่างคำขอ POST และการตรวจสอบแบบกลุ่ม

คำขอ POST สถานะของคำสั่งซื้อเดียว

curl -X POST "https:///orders/status" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_id":""}'

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

คำขอแบบกลุ่มสำหรับคำสั่งซื้อที่ใช้งานอยู่

หาก API รองรับการตรวจสอบแบบกลุ่ม ให้ส่งหลาย ID ในคำขอเดียว:

curl -X POST "https:///orders/statuses" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_ids":["",""]}'

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

กำหนด polling สำหรับ processing อย่างไร

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

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

• หลังสร้างคำสั่งซื้อ อย่าตรวจสอบสถานะซ้ำหลายครั้งติดกันทันที: บริการอาจต้องใช้เวลาในการเข้าคิว
• เมื่อ processing ซ้ำ ให้เพิ่มช่วงเวลาระหว่างคำขอ ไม่ใช่คงความถี่เดิม
• เพิ่มความคลาดเคลื่อนแบบสุ่มเล็กน้อยให้เวลาที่เริ่มงาน เพื่อไม่ให้คำสั่งซื้อหลายรายสอบถาม API พร้อมกัน
• หากผู้ให้บริการส่ง Retry-After หรือคำแนะนำที่เทียบเท่า ให้ใช้ค่านั้นเป็นลำดับความสำคัญ
• สำหรับคำสั่งซื้อที่มีเว็บฮุก ให้คง polling ควบคุมไว้: การแจ้งเตือนอาจไม่มาถึง

ข้อเสียของ polling ที่ห่างเกินไป — อินเทอร์เฟซอาจแสดงสถานะเก่าหลังจากเสร็จสิ้นจริงแล้ว ข้อเสียของ polling ที่ถี่เกินไป — เสี่ยงชนข้อจำกัด API ได้รับ 429 และสร้างภาระเกินจำเป็น

ต้องเก็บเวลาใดบ้างเพื่อควบคุม processing

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

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

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

ทำอย่างไรเมื่อ processing ไม่เปลี่ยน

processing ที่ยาวนานไม่ได้พิสูจน์ว่ามีข้อผิดพลาด ก่อนอื่นให้ตรวจสอบว่ามีการตอบกลับ API ที่สำเร็จเข้ามาหรือไม่ completed_quantity หรือ remains เปลี่ยนไปหรือไม่ มีเว็บฮุกหรือไม่ และกฎของบริการเปลี่ยนไปหรือไม่ การไม่เห็นการเติบโตอาจเกิดจากความหน่วงของสถิติแพลตฟอร์ม หรือผู้ให้บริการอัปเดตความคืบหน้าเฉพาะตอนจบเท่านั้น

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

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

ข้อเสียของการตรวจสอบด้วยตนเอง — คำสั่งซื้อต้องให้ความสนใจจากฝ่ายสนับสนุน แต่การยกเลิกอัตโนมัติหรือการทำซ้ำอันตรายกว่า: การดำเนินการอาจยังคงอยู่ที่ผู้ให้บริการ

แยกความล้มเหลวของคำขอออกจากสถานะคำสั่งซื้ออย่างไร

ข้อผิดพลาดเครือข่าย ไทม์เอาต์ HTTP 429 และการตอบกลับ 5xx ไม่ได้บอกสถานะของคำสั่งซื้อเอง สิ่งเหล่านี้หมายความเพียงว่าไม่สามารถรับสถานะใหม่ที่เชื่อถือได้ ในสถานการณ์เช่นนี้ ให้คงสถานะที่ยืนยันได้ครั้งล่าสุด บันทึกข้อผิดพลาดทางเทคนิค และวางแผนการตรวจสอบใหม่

เมื่อเกิด 429 ให้คำนึงถึง Retry-After หากมีเฮดเดอร์ส่งมา เมื่อเกิดข้อผิดพลาดเครือข่ายชั่วคราวและ 5xx ให้เพิ่มระยะห่างระหว่างความพยายาม เมื่อเกิดข้อผิดพลาดการรับรองสิทธิ์ ลายเซ็น หรือสิทธิ์การเข้าถึง อย่าตั้ง retry ถี่: ต้องตรวจสอบคีย์ อายุของโทเค็น ข้อจำกัด IP และการตั้งค่าการเข้าถึง

หาก API ส่ง HTTP 200 กลับมา แต่ JSON แยกวิเคราะห์ไม่ได้ หรือคำตอบไม่มี order_id และ status ให้บันทึกเนื้อหาคำตอบทั้งหมดและทำเครื่องหมายการตรวจสอบว่าไม่ถูกต้อง อย่าแทนที่การไม่มีสถานะด้วย completed, canceled หรือ processing

เมื่อใดควรหยุดคำขอซ้ำอัตโนมัติ

Polling ไม่ควรไม่มีที่สิ้นสุด จำกัดจำนวนการลองใหม่ทางเทคนิคสำหรับข้อผิดพลาดชั่วคราว และควบคุมระยะเวลารวมที่คำสั่งซื้ออยู่ใน processing แยกต่างหาก เมื่อใช้ครบขีดจำกัด retry แล้ว ให้ย้ายงานตรวจสอบเข้าคิววิเคราะห์ แทนที่จะสร้างคำขอใหม่ทุกนาทีโดยไม่มีผลลัพธ์

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

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

รับสถานะสุดท้ายหลัง processing อย่างไร

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

• new และ pending อาจเปลี่ยนเป็น processing, canceled หรือ failed
• processing อาจเปลี่ยนเป็น completed, partial, canceled หรือ failed
• partial ไม่ควรถือเป็น completed โดยอัตโนมัติ
• completed, canceled และ failed มักถือเป็นสถานะสุดท้ายและบล็อกการย้อนกลับอัตโนมัติ
• สถานะที่ไม่รู้จักหรือการเปลี่ยนที่ไม่ได้รับอนุญาตต้องได้รับการตรวจสอบแยก

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

จัดการ partial และยอดคงเหลือของคำสั่งซื้ออย่างไร

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

ตัวอย่างคำตอบสุดท้ายอาจมีลักษณะดังนี้:

{

"order_id": "",

"status": "partial",

"completed_quantity": 700,

"remains": 300,

"refund": "значение_или_отсутствие_поля"

}

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

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

เว็บฮุกไม่ได้แทนที่การตรวจสอบควบคุม

เว็บฮุกช่วยอัปเดตการ์ดคำสั่งซื้อทันทีหลังเหตุการณ์ โดยไม่ต้องรอ polling ครั้งถัดไป ในตัวจัดการ ให้ค้นหาคำสั่งซื้อด้วย ID ภายนอก ตรวจสอบลายเซ็นหรือความลับ บันทึก ID เหตุการณ์ และใช้การเปลี่ยนสถานะหลังจากตรวจสอบว่าอนุญาตแล้วเท่านั้น

การส่งเว็บฮุกซ้ำต้องปลอดภัย: เหตุการณ์เดียวกันไม่ควรถือเป็นการเปลี่ยนแปลงใหม่ เหตุการณ์อาจมาถึงไม่ตามลำดับ ดังนั้นอย่าเปลี่ยนคำสั่งซื้อที่เป็นสถานะสุดท้ายแล้วให้ย้อนกลับเพียงเพราะได้รับ processing ที่มาช้า

polling ควบคุมยังจำเป็นแม้เว็บฮุกจะเสถียร ข้อเสียของเว็บฮุก — การตั้งค่าซับซ้อนกว่า: ต้องมีตัวจัดการที่เข้าถึงได้ การป้องกันคำขอปลอม การขจัดข้อมูลซ้ำ และบันทึกเหตุการณ์

แสดงอะไรให้ลูกค้าเมื่อ processing และค้าง

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

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

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

ต้องมีบันทึกอะไรบ้างในบันทึกการประมวลผล

ประวัติการตอบกลับช่วยวิเคราะห์ processing ที่ค้าง เว็บฮุกที่สูญหาย ข้อโต้แย้งเกี่ยวกับการดำเนินการบางส่วน และความไม่ตรงกันระหว่างอินเทอร์เฟซกับ API สำหรับทุกการเรียก ให้บันทึก ID ภายนอก แหล่งที่มาของการอัปเดต เวลาคำขอและเวลาตอบกลับ รหัส HTTP สถานะต้นฉบับ สถานะที่ปรับให้เป็นมาตรฐาน ความคืบหน้า ยอดคงเหลือ และข้อความข้อผิดพลาดทางเทคนิค

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

ก่อนเปิดใช้งาน ให้ทดสอบสถานการณ์ที่มี processing ซ้ำ ไม่มีความคืบหน้า ไทม์เอาต์ 429 ข้อผิดพลาด 5xx JSON ไม่ถูกต้อง เว็บฮุกมาช้า เว็บฮุกซ้ำ partial canceled และสถานะที่ไม่รู้จัก โหมดทดสอบมีประโยชน์สำหรับโครงสร้างการเชื่อมต่อ แต่ข้อเสียคืออาจไม่จำลองคิวและความหน่วงจริงของ API ที่ใช้งานจริง