07.05 Shipment Tracking Best Practices

---

📌 At a Glance

รายการ	รายละเอียด
Topic	Shipment Tracking Best Practices
Difficulty	⭐⭐ Intermediate
Reading Time	8 นาที
Target	Developer, System Integrator

---

🎯 Learning Objectives

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

• ออกแบบระบบติดตามสถานะสินค้าได้อย่างมีประสิทธิภาพ
• ลดจำนวนการเรียก API ที่ไม่จำเป็น
• จัดการข้อมูลสถานะการจัดส่งได้อย่างถูกต้อง
• พัฒนาระบบที่รองรับการใช้งานจริงในระดับ Production

---

Overview

Shipment Tracking API เป็นบริการสำหรับติดตามสถานะการจัดส่งสินค้าใน SISAHYGO Integration Platform

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

หัวข้อนี้รวบรวมแนวทางปฏิบัติที่แนะนำสำหรับการพัฒนา Client System เพื่อให้สามารถใช้งาน Shipment Tracking API ได้อย่างมีประสิทธิภาพ

---

Figure 7-5 Shipment Tracking Best Practices

Figure 7-5 แสดงแนวทางการติดตามสถานะการจัดส่ง ตั้งแต่การจัดเก็บ Order ID การเรียก API การอัปเดตข้อมูล และการแสดงผลในระบบของผู้ใช้งาน

---

Recommended Workflow

Store Order ID

      │

      ▼

Call Shipment Tracking API

      │

      ▼

Receive Response

      │

      ▼

Update Local Database

      │

      ▼

Display Current Status

      │

      ▼

Show Shipment Timeline

---

Recommended Practices

Practice	Recommendation
Store Order ID	จัดเก็บ id เป็นเลขอ้างอิงหลัก
Use Pagination	ใช้ per_page เมื่อต้องดึงข้อมูลจำนวนมาก
Filter Data	ใช้ from_date, to_date และ order_status เพื่อลดปริมาณข้อมูล
Cache Master Data	ไม่ต้องเรียก Master Data ซ้ำทุกครั้ง
Save History	จัดเก็บประวัติการเปลี่ยนสถานะสำหรับการตรวจสอบย้อนหลัง

---

API Usage Recommendations

สำหรับการเรียก API

• ใช้ GET /shipments/{tracking_no} เมื่อต้องการข้อมูลของรายการเดียว
• ใช้ GET /shipments เมื่อต้องการรายการหลายรายการ
• ใช้ Query Parameters เพื่อลดขนาดข้อมูลที่ส่งกลับ
• ไม่ควรดึงข้อมูลทั้งหมดโดยไม่กำหนดเงื่อนไข

---

Local Database Recommendation

Client System ควรจัดเก็บข้อมูลอย่างน้อยดังนี้

Field	Purpose
id	เลขอ้างอิงหลักของรายการ
client_reference_no	เชื่อมโยงกับ ERP
order_header_no	เลขที่ใบรับส่งสินค้า
order_status	สถานะล่าสุด
updated_at	เวลาที่อัปเดตล่าสุด

---

Status Synchronization

แนะนำให้อัปเดตสถานะตามรอบเวลาที่เหมาะสม เช่น

Use Case	Recommendation
Dashboard	ทุก 5–10 นาที
Customer Portal	ทุก 5 นาที
ERP Integration	ทุก 10–15 นาที
Manual Tracking	เรียก API เมื่อผู้ใช้ร้องขอ

ระยะเวลาข้างต้นเป็นคำแนะนำทั่วไป สามารถปรับให้เหมาะสมกับลักษณะการใช้งานและปริมาณข้อมูลของแต่ละระบบ

---

Error Handling

Situation	Recommendation
HTTP 401	ตรวจสอบ API Key
HTTP 404	ตรวจสอบ Order ID
HTTP 500	บันทึกข้อผิดพลาดและลองใหม่ภายหลัง
Network Timeout	ลองเรียกใหม่เมื่อการเชื่อมต่อกลับมาปกติ

---

Performance Recommendations

• ใช้ Pagination ทุกครั้งเมื่อดึงข้อมูลจำนวนมาก
• กรองข้อมูลด้วยช่วงวันที่
• ใช้ id เป็น Primary Identifier
• ลดการเรียก API ซ้ำโดยจัดเก็บข้อมูลไว้ใน Local Database

---

Security Recommendations

• ใช้ HTTPS ทุกครั้ง
• เก็บ API Key ไว้ในตำแหน่งที่ปลอดภัย
• ไม่ส่ง API Key ผ่าน URL
• จำกัดสิทธิ์การเข้าถึง API ตามความจำเป็น

---

Integration Checklist

ก่อนนำระบบขึ้นใช้งานจริง

• [x] จัดเก็บ Order ID (id)
• [x] รองรับ Pagination
• [x] รองรับ Query Parameters
• [x] แสดง Timeline จาก history
• [x] บันทึก Response สำหรับตรวจสอบย้อนหลัง
• [x] รองรับ HTTP Error
• [x] ใช้งานผ่าน HTTPS

---

Related APIs

• POST /order-checkings
• GET /shipments
• GET /shipments/

---

Summary

Shipment Tracking API ช่วยให้ Client System สามารถติดตามสถานะการจัดส่งสินค้าได้อย่างต่อเนื่อง การจัดเก็บ Order ID (id) การใช้ Query Parameters อย่างเหมาะสม และการอัปเดตข้อมูลใน Local Database จะช่วยลดภาระของระบบ เพิ่มประสิทธิภาพในการแสดงผล และรองรับการใช้งานจริงในระดับ Production ได้อย่างมีประสิทธิภาพ

---

Next Step

➡️ 07.06 Chapter Summary