ฟิลด์ใดในผลตอบกลับของ Tracking API ที่ใช้สร้างไทม์ไลน์การติดตามการจัดส่งที่สมบูรณ์?
ไทม์ไลน์การติดตามการจัดส่งที่สมบูรณ์ต้องมีมากกว่าสถานะปัจจุบัน สำหรับเหตุการณ์การติดตามแต่ละรายการ ให้เก็บรหัสระบุการจัดส่ง เวลาที่เกิดเหตุการณ์ คำอธิบายหรือรหัสเหตุการณ์ของผู้ให้บริการ สถานะมาตรฐานเมื่อมีข้อมูล และตำแหน่งที่เกิดเหตุการณ์เมื่อมีการระบุไว้ เพิ่มบริบทของผู้ให้บริการและหมายเลขติดตาม รายละเอียดการจัดส่งหรือข้อยกเว้น ตลอดจนวิธีรักษาลำดับและการอัปเดตของเหตุการณ์ ชื่อฟิลด์ที่แน่นอนจะแตกต่างกันไปตาม API เป้าหมายคือการสร้างภาพขึ้นใหม่ว่าเกิดอะไรขึ้น เมื่อใด ที่ไหน และเกิดขึ้นกับพัสดุชิ้นใด
สำหรับนักพัฒนาที่สร้างหน้าคำสั่งซื้อ แดชบอร์ดฝ่ายสนับสนุน หรือเวิร์กโฟลว์ด้านโลจิสติกส์ ความแตกต่างที่มีประโยชน์ที่สุดคือระหว่าง สรุปการจัดส่ง และ ประวัติเหตุการณ์ สรุปจะตอบว่า “สถานะล่าสุดที่ทราบคืออะไร” ไทม์ไลน์จะตอบว่า “การจัดส่งมาถึงสถานะนั้นได้อย่างไร” ทั้งสองอย่างจำเป็น แต่ไม่ควรถือว่าใช้แทนกันได้
เริ่มต้นด้วยข้อมูลระบุการจัดส่ง ไม่ใช่สถานะ
ทุกเหตุการณ์ต้องเชื่อมโยงกับการจัดส่งที่ถูกต้อง หมายเลขติดตามมักเป็นจุดเริ่มต้น แต่ไม่ควรเป็นตัวระบุเพียงอย่างเดียวในโมเดลข้อมูลภายใน เก็บตัวระบุการจัดส่งหรือระเบียนการติดตามของ API หากมีการส่งมา พร้อมกับตัวระบุคำสั่งซื้อและพัสดุของคุณเอง บันทึกตัวระบุหรือชื่อผู้ให้บริการ และบริบทปลายทางหรือต้นทางที่ใช้ระบุการจัดส่งเมื่อเกี่ยวข้อง
เรื่องนี้มีความสำคัญเมื่อคำสั่งซื้อมีพัสดุหลายชิ้น หมายเลขติดตามถูกแก้ไข หรือการส่งต่อทำให้มีผู้ให้บริการหรือหมายเลขอ้างอิงอื่นเข้ามา หาก API แสดงหมายเลขติดตามที่เกี่ยวข้องหรือรายละเอียดการส่งต่อระหว่างผู้ให้บริการ ให้จัดเก็บความสัมพันธ์ดังกล่าวแทนการรวมประวัติสองชุดเข้าด้วยกันเพียงเพราะอยู่ในคำสั่งซื้อเดียวกัน คำสั่งซื้อหนึ่งรายการอาจมีไทม์ไลน์การจัดส่งที่ถูกต้องได้หลายชุด
ในระดับเหตุการณ์ ชุดข้อมูลระบุที่ใช้งานได้จริงประกอบด้วยข้อมูลอ้างอิงการจัดส่ง ผู้ให้บริการที่รับผิดชอบเหตุการณ์เมื่อทราบ และตัวระบุเหตุการณ์ที่คงที่ซึ่ง API จัดหาให้ หรือข้อมูลต้นทางที่เพียงพอสำหรับระบุเหตุการณ์ที่เกิดซ้ำ อย่าคิดว่าการสแกนสองรายการที่มีสถานะเดียวกันเป็นรายการซ้ำเสมอไป พัสดุอาจได้รับการสแกนประเภทเดียวกันที่ศูนย์คัดแยกหรือในเวลาที่แตกต่างกัน
ฟิลด์การตอบกลับที่ทำให้แต่ละเหตุการณ์มีประโยชน์
ชื่อฟิลด์ เช่น event_time และ status ด้านล่าง อธิบายบทบาทของข้อมูล ไม่ใช่โครงสร้างสคีมาแบบสากลของ tracking API ให้แมปฟิลด์เหล่านี้กับการตอบกลับจริงที่ผู้ให้บริการของคุณจัดทำเป็นเอกสารไว้
- เวลาเหตุการณ์: เวลาที่ผู้ให้บริการระบุว่าเหตุการณ์เกิดขึ้น เก็บค่าดั้งเดิมและข้อมูลเขตเวลาเมื่อมีการระบุ โดยปกติค่านี้คือเวลาหลักสำหรับไทม์ไลน์ที่แสดงต่อลูกค้า
- คำอธิบายเหตุการณ์หรือรหัสของผู้ให้บริการ: ข้อความการสแกนต้นฉบับหรือรหัสเหตุการณ์ที่เครื่องอ่านได้ การเก็บค่าต้นทางทำให้ตรวจสอบป้ายกำกับมาตรฐานย้อนหลังได้ และช่วยให้ทีมสนับสนุนตรวจสอบการสแกนที่ไม่คุ้นเคย
- สถานะมาตรฐาน: หมวดหมู่ระดับผู้ให้บริการหรือแอปพลิเคชัน เช่น อยู่ระหว่างการขนส่ง กำลังนำจ่าย จัดส่งแล้ว หรือมีข้อยกเว้น ใช้เพื่อจัดกลุ่มเหตุการณ์ แต่อย่าให้มาแทนที่รายละเอียดการสแกนต้นฉบับ
- ตำแหน่ง: ศูนย์คัดแยก เมือง ภูมิภาค ประเทศ หรือฟิลด์ตำแหน่งอื่นที่ผู้ให้บริการจัดส่งให้จริง แสดงเฉพาะระดับความละเอียดที่มีอยู่ในการตอบกลับ อย่าเปลี่ยนการสแกนระดับประเทศให้กลายเป็นตำแหน่งระดับถนนโดยนัย
- บริบทผู้ให้บริการและการติดตาม: ตัวระบุผู้ให้บริการ หมายเลขติดตาม และหมายเลขที่เกี่ยวข้องซึ่งจำเป็นต่อการอธิบายการส่งต่อหรือแยกพัสดุแต่ละชิ้น
- ข้อมูลเมตาของเหตุการณ์: ตัวระบุเหตุการณ์ต้นทาง หมายเลขลำดับ หรือข้อมูลอ้างอิงอื่นของผู้ให้บริการ หากมี ฟิลด์เหล่านี้ช่วยในการลบรายการซ้ำ การแก้ไข และการจัดลำดับที่คงที่
ยังสามารถสร้างไทม์ไลน์ที่มีประโยชน์ได้แม้ฟิลด์เสริมบางรายการจะหายไป ตัวอย่างเช่น เหตุการณ์ “จัดส่งแล้ว” ที่ถูกต้องอาจไม่มีตำแหน่งจัดส่งสาธารณะ แอปพลิเคชันควรแสดงเหตุการณ์ที่ยืนยันแล้วโดยไม่สร้างตำแหน่งหรือผู้รับขึ้นมาเอง
แยกเวลาเหตุการณ์ออกจากเวลาประมวลผล
ระบบติดตามอาจแสดงเวลาหลายประเภท ได้แก่ เวลาที่เกิดการสแกน เวลาที่ผู้ให้บริการเผยแพร่ข้อมูล เวลาที่ผู้ให้บริการ API บันทึกข้อมูล และเวลาที่แอปพลิเคชันของคุณได้รับข้อมูล แต่ละเวลาตอบคำถามที่แตกต่างกัน ให้จัดเรียงเส้นทางที่แสดงโดยใช้เวลาที่เหตุการณ์เกิดขึ้นเป็นหลักเมื่อเวลานั้นเชื่อถือได้ ใช้เวลานำเข้าเพื่ออธิบายว่าระบบของคุณทราบเหตุการณ์เมื่อใด และเพื่อตรวจจับการอัปเดตที่มาถึงล่าช้า
ข้อมูลที่มาถึงล่าช้าเป็นเรื่องปกติพอที่จะต้องออกแบบระบบรองรับ ผู้ให้บริการอาจเผยแพร่การสแกนก่อนหน้า หลังจากที่การสแกนภายหลังปรากฏแล้ว หากแอปพลิเคชันเพียงเพิ่มการตอบกลับ API ใหม่ทุกครั้งไว้ด้านล่างของหน้า ไทม์ไลน์ที่ได้อาจเรียงลำดับเวลาไม่ถูกต้อง ให้ตรวจสอบเหตุการณ์กับประวัติที่จัดเก็บไว้ แล้วจัดเรียงตามกฎที่มีการบันทึกไว้ หากเหตุการณ์สองรายการมีเวลาเกิดขึ้นเท่ากัน ลำดับต้นทางหรือตัวระบุเหตุการณ์อาจใช้เป็นตัวตัดสินได้ มิฉะนั้นให้รักษาลำดับภายในที่กำหนดได้แน่นอน โดยไม่อ้างว่าต้นทางเป็นผู้กำหนดลำดับดังกล่าว
การจัดการเขตเวลาต้องได้รับความสนใจเป็นพิเศษ การจัดเก็บสามารถทำให้เวลาที่มีออฟเซ็ตเป็นมาตรฐานได้ ขณะเดียวกันยังคงเก็บเวลาต้นฉบับไว้สำหรับการแสดงผลหรือการตรวจสอบ เวลาที่ไม่มีการระบุออฟเซ็ตไม่ควรถูกตีความเป็น UTC โดยอัตโนมัติ สำหรับการผสานรวมที่รับหรือส่งเวลาบนอินเทอร์เน็ต RFC 3339 เป็นข้อมูลอ้างอิงที่มีประโยชน์สำหรับรูปแบบเวลา แต่ไม่ได้บอกด้วยตัวเองว่าผู้ให้บริการตั้งใจใช้เขตเวลาใดเมื่อข้อมูลไม่ได้ระบุไว้
แยกสถานะล่าสุดออกจากประวัติทั้งหมด
การตอบกลับการติดตามจำนวนมากมีทั้งสถานะปัจจุบันของการจัดส่งและรายการเหตุการณ์ย้อนหลัง สถานะปัจจุบันมีประโยชน์สำหรับการ์ดคำสั่งซื้อขนาดกะทัดรัด การกรอง และการแจ้งเตือน ส่วนประวัติคือแหล่งข้อมูลสำหรับลำดับการสแกน อย่าสร้างเหตุการณ์ย้อนหลังใหม่ทุกครั้งที่เรียกดูสถานะปัจจุบันที่ไม่เปลี่ยนแปลง และอย่าทิ้งเหตุการณ์เก่าเพียงเพราะออบเจ็กต์สถานะล่าสุดมีข้อมูลครบถ้วน
นอกจากนี้ อย่าคิดว่ารายการสุดท้ายในอาร์เรย์คือการสแกนล่าสุดเสมอไป ตรวจสอบกฎการจัดลำดับของผู้ให้บริการ แล้วจัดเรียงหรือตรวจสอบให้สอดคล้องกัน การตอบกลับอาจมีประวัติเพียงบางส่วน หรือการผสานรวมอาจต้องดึงข้อมูลหลายหน้า หาก API ระบุการแบ่งหน้าหรือจำกัดจำนวนประวัติ ให้ปฏิบัติตามกลไกดังกล่าวก่อนอธิบายว่าเส้นทางที่แสดงนั้นสมบูรณ์ หากไม่มีประวัติ ให้ระบุว่ามุมมองนี้คือเหตุการณ์ที่ได้รับ แทนการสื่อว่าไม่มีการสแกนก่อนหน้านี้
สำหรับโครงสร้างภายในที่มีความทนทาน ให้จัดเก็บการตอบกลับดิบหรือฟิลด์ต้นทางที่จำเป็นต่อการสร้างความหมายที่คุณตีความขึ้นใหม่ พร้อมกับระเบียนเหตุการณ์มาตรฐาน การเก็บค่าต้นทางมีคุณค่าอย่างยิ่งเมื่อการแมปมีการเปลี่ยนแปลง เพราะคุณสามารถประมวลผลเหตุการณ์เก่าใหม่ได้โดยไม่ต้องขอให้ผู้ให้บริการสร้างข้อมูลที่อาจเรียกคืนไม่ได้อีกครั้ง
จัดการเหตุการณ์สำคัญ ข้อยกเว้น และหลักฐานการจัดส่งอย่างรอบคอบ
ป้ายกำกับสถานะไม่ได้เป็นเหตุการณ์สำคัญเสมอไป “อยู่ระหว่างการขนส่ง” อาจสรุปการสแกนหลายรายการ ขณะที่ “กำลังนำจ่าย” และ “จัดส่งแล้ว” มักเป็นขั้นตอนที่แตกต่างกัน สร้างเหตุการณ์สำคัญจากความหมายของเหตุการณ์ที่มีเอกสารรองรับ แทนการสมมติว่าผู้ให้บริการทุกรายใช้ถ้อยคำเหมือนกัน หากสถานะไม่ชัดเจน ให้แสดงคำอธิบายต้นฉบับและหลีกเลี่ยงการเพิ่มข้อสรุปที่หนักแน่นกว่า
เหตุการณ์ข้อยกเว้นต้องมีทั้งหมวดหมู่และรายละเอียดของผู้ให้บริการเมื่อมีข้อมูล “พยายามจัดส่งแล้ว” ให้ข้อมูลคนละแบบกับ “รอพิธีการศุลกากร” แม้แอปพลิเคชันจะจัดทั้งสองกรณีไว้ในสถานะต้องดำเนินการก็ตาม เก็บข้อความเหตุผล รหัสเหตุผล และข้อมูลการดำเนินการถัดไปเป็นฟิลด์แยกกัน หากการตอบกลับมีข้อมูลเหล่านี้ เจ้าหน้าที่ฝ่ายสนับสนุนจะสามารถแยกความล่าช้าชั่วคราวออกจากเหตุการณ์ที่ผู้รับอาจต้องดำเนินการได้
การยืนยันการจัดส่งก็ควรได้รับการจัดการอย่างระมัดระวังเช่นกัน หากการตอบกลับมีเหตุการณ์จัดส่งแล้ว ให้บันทึกเวลาและตำแหน่งหรือรายละเอียดผู้รับที่มีอยู่ หากมีข้อมูลหลักฐานการจัดส่ง ให้เก็บประเภทหลักฐานและข้อจำกัดการเข้าถึงที่ผู้ให้บริการกำหนดไว้ อย่าสรุปว่ามีลายเซ็น ภาพถ่าย หรือผู้รับที่ระบุชื่อจากสถานะจัดส่งแล้วเพียงอย่างเดียว ในทำนองเดียวกัน วันที่จัดส่งโดยประมาณเป็นการคาดการณ์ ไม่ใช่เหตุการณ์ที่เสร็จสิ้นแล้ว ควรแสดงแยกจากไทม์ไลน์ย้อนหลัง
เวิร์กโฟลว์การแมปที่ใช้งานได้จริงสำหรับนักพัฒนา
- ตรวจสอบการตอบกลับจริงและเอกสารประกอบ ระบุออบเจ็กต์ระดับการจัดส่ง อาร์เรย์เหตุการณ์ รูปแบบเวลา คำศัพท์สถานะ และขีดจำกัดหรือการแบ่งหน้าที่มีการบันทึกไว้ อย่าสมมติว่าชื่อฟิลด์ตัวอย่างในบทความตรงกับสคีมาที่ใช้งานจริง
- กำหนดโมเดลเหตุการณ์ภายในหนึ่งรูปแบบ รวมข้อมูลระบุการจัดส่ง ผู้ให้บริการต้นทาง เวลาเกิดเหตุการณ์ ข้อความหรือรหัสสถานะต้นฉบับ หมวดหมู่มาตรฐาน ตำแหน่งเสริม ตัวระบุเหตุการณ์ต้นทาง และเวลาที่ได้รับ กำหนดฟิลด์เสริมให้รับค่า null แทนการเติมข้อมูลที่คาดเดา
- เขียนกฎการแมปอย่างชัดเจน บันทึกว่าแต่ละฟิลด์ต้นทางกลายเป็นฟิลด์ภายในอย่างไร และค่าต้นทางใดรองรับสถานะมาตรฐานแต่ละรายการ เก็บรหัสที่ไม่รู้จักไว้ให้ตรวจสอบ แทนการบังคับให้เข้ากับเหตุการณ์สำคัญที่ไม่ถูกต้อง
- ตรวจสอบการตอบกลับซ้ำ ใช้ตัวระบุเหตุการณ์ที่มีเอกสารรองรับเมื่อมี หากไม่มี ให้กำหนดกฎการจับคู่ที่ระมัดระวังโดยใช้ค่าต้นทางที่คงที่ และทดสอบกับการสแกนหลายรายการที่มีสถานะเดียวกันโดยชอบธรรม
- ทดสอบเส้นทางที่ซับซ้อน รวมพัสดุหลายชิ้น การสแกนที่มาถึงล่าช้า เวลาเท่ากัน การส่งต่อระหว่างผู้ให้บริการ การพยายามจัดส่ง ตำแหน่งที่หายไป การเปลี่ยนแปลงวันที่โดยประมาณ และเหตุการณ์จัดส่งแล้วที่มีรายละเอียดการยืนยันจำกัด
- ตรวจสอบสิ่งที่ UI สัญญาไว้ ไทม์ไลน์ควรแยกเหตุการณ์ที่สังเกตได้ออกจากการคาดการณ์ รักษาความไม่แน่นอน และหลีกเลี่ยงการนำเสนอประวัติที่ไม่สมบูรณ์ว่าเป็นข้อมูลทั้งหมดของการจัดส่ง
สำหรับการผสานรวม 17TRACK Tracking API ให้ใช้ เอกสาร API อย่างเป็นทางการ เพื่อยืนยันโครงสร้างการตอบกลับและความหมายของฟิลด์จริงก่อนดำเนินการแมป ฟิลด์ในคู่มือนี้เป็นรายการตรวจสอบสำหรับการนำไปใช้ ไม่ใช่การยืนยันว่า 17TRACK ส่งคืนฟิลด์ด้วยชื่อเหล่านี้ทุกประการ หรือผู้ให้บริการทุกรายมีรายละเอียดครบทุกอย่าง
อะไรคือไทม์ไลน์ที่สมบูรณ์
ไทม์ไลน์ถือว่าสมบูรณ์สำหรับแอปพลิเคชันของคุณเมื่อเชื่อมโยงแต่ละเหตุการณ์ที่แสดงกับพัสดุที่ถูกต้อง เก็บเหตุการณ์ต้นทางและเวลาของเหตุการณ์ไว้ จัดลำดับเหตุการณ์ที่ทราบอย่างสอดคล้องกัน และแสดงสถานะ ตำแหน่ง ข้อยกเว้น และการยืนยันการจัดส่งเท่าที่การตอบกลับรองรับ ความสมบูรณ์ในเชิงปฏิบัติการยังต้องรู้ขอบเขตของข้อมูลด้วยว่า API ส่งคืนประวัติที่มีอยู่ทั้งหมด ช่วงข้อมูลที่จำกัด หรือเหตุการณ์จากผู้ให้บริการหรือระเบียนการติดตามเฉพาะราย
การทดสอบการยอมรับที่ดีที่สุดไม่ใช่จำนวนฟิลด์ที่มีข้อมูล แต่คือการที่ลูกค้าหรือเจ้าหน้าที่ฝ่ายสนับสนุนสามารถอ่านเส้นทางได้โดยไม่ถูกทำให้เข้าใจผิด หากแอปพลิเคชันตอบได้ว่าเกิดอะไรขึ้น เมื่อใด เกี่ยวข้องกับการจัดส่งใด และยังมีสิ่งใดไม่แน่นอน ฟิลด์การตอบกลับก็ทำหน้าที่ของมันได้ดี
คำถามที่พบบ่อย
ฟิลด์สถานะปัจจุบันเพียงพอสำหรับสร้างไทม์ไลน์การจัดส่งหรือไม่
ไม่เพียงพอ สถานะปัจจุบันให้ภาพ ณ ช่วงเวลาหนึ่ง ไทม์ไลน์ต้องมีระเบียนเหตุการณ์ย้อนหลังพร้อมเวลาและบริบทที่จำเป็นต่อการเชื่อมโยงแต่ละระเบียนกับการจัดส่งที่ถูกต้อง
ควรแสดงข้อความการสแกนของผู้ให้บริการหรือเฉพาะสถานะมาตรฐาน
เก็บทั้งสองอย่างเมื่อ API มีข้อมูล สถานะมาตรฐานทำให้อ่านเส้นทางได้ง่ายขึ้น ส่วนคำอธิบายต้นฉบับยังคงรายละเอียดและช่วยอธิบายเหตุการณ์ที่ผิดปกติหรือเฉพาะผู้ให้บริการ
ควรใช้เวลาใดกำหนดลำดับเหตุการณ์
ใช้เวลาเกิดเหตุการณ์เมื่อความหมายและเขตเวลามีความชัดเจนเพียงพอ เก็บเวลาที่ API ได้รับข้อมูลแยกไว้ และกำหนดตัวตัดสินที่คงที่สำหรับเหตุการณ์ที่มีเวลาเกิดขึ้นเหมือนกันหรือไม่แน่นอน
หากเหตุการณ์การติดตามไม่มีตำแหน่งควรทำอย่างไร
แสดงเหตุการณ์โดยไม่ต้องมีตำแหน่ง การขาดข้อมูลตำแหน่งไม่ได้ทำให้เหตุการณ์ไม่ถูกต้อง แต่ก็ไม่เป็นเหตุผลให้อนุมานศูนย์คัดแยก เมือง หรือที่อยู่จัดส่งขึ้นมา
จะทราบได้อย่างไรว่า API ส่งคืนเส้นทางทั้งหมด
ตรวจสอบเอกสารของผู้ให้บริการเกี่ยวกับขอบเขตประวัติ การแบ่งหน้า และขีดจำกัดการตอบกลับ จากนั้นตรวจสอบว่าการผสานรวมของคุณดึงเหตุการณ์เพิ่มเติมอย่างไร หากไม่สามารถยืนยันขอบเขตได้ ให้อธิบายว่าไทม์ไลน์คือเหตุการณ์ที่แอปพลิเคชันของคุณเข้าถึงได้
แหล่งข้อมูล
- ภาพรวม 17TRACK Tracking API — บริบทผลิตภัณฑ์สำหรับตัวอย่างการผสานรวม
- เอกสาร 17TRACK API — ข้อมูลอ้างอิงสำหรับตรวจสอบฟิลด์และพฤติกรรมของการตอบกลับที่ใช้ในการนำไปใช้งานจริง
- RFC 3339: วันที่และเวลาบนอินเทอร์เน็ต — ข้อมูลอ้างอิงสำหรับรูปแบบเวลา


