07.04 Shipment Status History

---

📌 At a Glance

รายการ	รายละเอียด
Topic	Shipment Status History
Difficulty	⭐⭐⭐ Intermediate
Reading Time	10 นาที
Target	Developer

---

🎯 Learning Objectives

หลังจากศึกษาหัวข้อนี้แล้ว ผู้อ่านจะสามารถ

• เข้าใจโครงสร้างข้อมูล history
• แสดง Timeline ของการจัดส่งได้
• ติดตามการเปลี่ยนแปลงสถานะของ Shipment
• ออกแบบหน้าจอติดตามสถานะสินค้าได้

---

Overview

Shipment Tracking API ส่งประวัติการเปลี่ยนสถานะของรายการผ่านฟิลด์ history

ข้อมูลนี้เรียงลำดับตามเวลาที่เกิดเหตุการณ์จริง และสามารถใช้สร้าง Timeline การจัดส่ง หรือแสดงความคืบหน้าของรายการใน Client System ได้

---

Figure 7-4 Shipment Status History

Figure 7-4 แสดงลำดับการเปลี่ยนสถานะของ Shipment ตามข้อมูลที่ส่งกลับจากฟิลด์ history ใน Shipment Tracking API

---

History Object

ตัวอย่างข้อมูล

"history": [
    {
        "status": "new",
        "changed_at": "2026-07-01T10:20:00+07:00"
    },
    {
        "status": "confirmed",
        "changed_at": "2026-07-01T10:35:00+07:00"
    },
    {
        "status": "loaded",
        "changed_at": "2026-07-01T11:10:00+07:00"
    },
    {
        "status": "in transit",
        "changed_at": "2026-07-01T12:45:00+07:00"
    },
    {
        "status": "completed",
        "changed_at": "2026-07-01T15:30:00+07:00"
    }
]

---

History Fields

Field	Type	Description
status	String	สถานะของรายการ
changed_at	DateTime	วันที่และเวลาที่เปลี่ยนสถานะ (ISO 8601)

---

Shipment Status Reference

Status	Description
new	ตรวจสอบข้อมูลเรียบร้อย
confirmed	สร้างใบรับส่งสินค้าแล้ว
loaded	ขึ้นสินค้าขึ้นรถแล้ว
in transit	อยู่ระหว่างการขนส่ง
completed	ส่งมอบสินค้าเรียบร้อย

---

Timeline Example

10:20

new

↓

10:35

confirmed

↓

11:10

loaded

↓

12:45

in transit

↓

15:30

completed

---

Business Notes

• ประวัติสถานะเรียงจากเก่าไปใหม่
• ทุกเหตุการณ์มีวันที่และเวลาที่บันทึก
• เวลาถูกส่งในรูปแบบ ISO 8601
• จำนวนเหตุการณ์ขึ้นอยู่กับการดำเนินงานจริงของแต่ละ Shipment

---

UI Recommendations

แนะนำให้แสดงข้อมูลในรูปแบบ

• Vertical Timeline
• Progress Tracker
• Shipment History Table

เพื่อให้ผู้ใช้งานเข้าใจสถานะได้ง่าย

---

Implementation Notes

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

---

Best Practices

• ใช้ history แสดง Timeline ให้ผู้ใช้งาน
• แสดงวันและเวลาตาม Time Zone ของผู้ใช้
• Highlight สถานะล่าสุด
• เก็บข้อมูลไว้สำหรับ Audit Log หากจำเป็น

---

Related APIs

• GET /shipments
• GET /shipments/

---

Summary

ฟิลด์ history เป็นส่วนสำคัญของ Shipment Tracking API ที่ช่วยให้ Client System สามารถแสดงลำดับเหตุการณ์ของการจัดส่งได้อย่างครบถ้วน โดยแต่ละเหตุการณ์ประกอบด้วยสถานะและเวลาที่เกิดขึ้นจริง ทำให้สามารถสร้าง Timeline หรือ Progress Tracking ที่สะท้อนกระบวนการขนส่งของ SISAHYGO ได้อย่างชัดเจน

---

Next Step

➡️ 07.05 Integration Best Practices