ภาพรวม
KabyTech batch API ออกแบบมาสำหรับการรับข้อมูลปริมาณมาก แทนที่จะรอให้แต่ละเอกสารเสร็จก่อนส่งถัดไป คุณส่งทั้ง batch แล้วรับผลลัพธ์ผ่าน webhook callbacks ที่ส่งตาม progress ของแต่ละเอกสาร วิธีนี้ทำให้คุณประมวลผลเอกสารหลายพันฉบับต่อชั่วโมงโดยไม่ต้องจัดการ connection pooling หรือ rate limiting ด้วยตัวเอง
บทเรียนนี้ครอบคลุมสามส่วนหลัก: การส่ง batch การลงทะเบียนและจัดการ webhooks และการจัดการข้อผิดพลาดพร้อมกลยุทธ์ retry API รองรับ batch ที่มีเอกสารสูงสุด 5,000 ฉบับต่อคำขอ
ขั้นตอนที่ 1 — ส่ง Batch
สร้าง batch โดย POST JSON manifest ที่ระบุรายการเอกสารที่ต้องการประมวลผล แต่ละรายการสามารถอ้างอิงไฟล์ด้วย URL หรือ file ID ที่อัปโหลดไว้ก่อนหน้า กำหนด doc_type ต่อรายการ (เช่น awb, bl, commercial_invoice) หรือใช้ auto เพื่อให้ API ตรวจจับอัตโนมัติ
Response จะส่งกลับ batch_id ทันที ไม่ต้องรอจนกว่าจะประมวลผลเสร็จ ใช้ batch_id เพื่อตรวจสอบสถานะหรือยกเลิก batch เวลาประมวลผลขึ้นอยู่กับจำนวนเอกสารและประเภท โดยทั่วไป 1,000 AWB ใช้เวลาประมาณ 8 นาที
ขั้นตอนที่ 2 — ลงทะเบียนและจัดการ Webhooks
webhook_url ในคำขอ batch ของคุณจะได้รับ POST สำหรับเอกสารที่เสร็จแต่ละฉบับ payload ประกอบด้วย document ID ข้อมูลที่ดึงได้ คะแนนความมั่นใจ และสถานะข้อผิดพลาด (ถ้ามี) คุณต้อง respond ด้วย 200 OK ภายใน 5 วินาที มิฉะนั้น API จะ retry สูงสุด 3 ครั้งด้วย exponential backoff
ปลอดภัยที่สุดคือคิวงาน webhook payloads ลง database หรือ message queue ก่อน แล้วจึงประมวลผลแบบ async ซึ่งป้องกัน webhook timeout และช่วยให้คุณ replay events ได้หากเกิดปัญหา ลง signature ของ webhook payloads ด้วย HMAC-SHA256 ใช้ shared secret เพื่อยืนยันว่า payloads มาจาก KabyTech
ขั้นตอนที่ 3 — การจัดการข้อผิดพลาดและกลยุทธ์ Retry
ไม่ใช่ทุกเอกสารจะสำเร็จในครั้งแรก สาเหตุความล้มเหลวที่พบบ่อยรวมถึงไฟล์เสียหาย รูปแบบที่ไม่รองรับ และภาพที่มีความละเอียดต่ำมาก webhook payload มีฟิลด์ error_code และ error_detail สำหรับการวินิจฉัย
สำหรับข้อผิดพลาดชั่วคราว (เช่น timeout หรือ rate limits) ให้ retry ด้วย exponential backoff API มี endpoint POST /batches/{batch_id}/retry เฉพาะสำหรับเรื่องนี้ ซึ่ง retry เฉพาะเอกสารที่ล้มเหลว ไม่ใช่ทั้ง batch สำหรับข้อผิดพลาดถาวร (ไฟล์เสียหาย ไม่ใช่ freight document) ให้บันทึกไว้สำหรับการตรวจสอบด้วยมือ อย่า retry เนื่องจากจะล้มเหลวซ้ำแน่นอน
สรุป
Batch processing ด้วย webhooks ช่วยให้คุณ scale จากเอกสารสิบฉบับเป็นพันฉบับโดยไม่ต้องเปลี่ยน integration architecture ส่ง manifest รับผลลัพธ์ตามที่เอกสารเสร็จ และจัดการความล้มเหลวด้วย retry ที่กำหนดเป้าหมาย
ประเด็นสำคัญ: ใช้ webhook callbacks แทนการ poll เพื่อประสิทธิภาพ ตรวจสอบ webhook signatures ด้วย HMAC-SHA256 คิวงาน payloads ก่อนประมวลผล และใช้ endpoint retry ที่กำหนดเป้าหมายสำหรับความล้มเหลวชั่วคราว สำหรับปริมาณเกิน 5,000 เอกสาร ให้แบ่งเป็นหลาย batch และประมวลผลแบบคู่ขนาน
ต้องการประมวลผลเอกสารในปริมาณมาก?
Batch API จัดการเอกสารขนส่งสินค้าหลายพันฉบับพร้อม retry logic ในตัว