API ติดตามพัสดุ UPS: คู่มือสำหรับผู้เริ่มต้นในการเริ่มต้นใช้งาน

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

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

UPS Tracking API ทำอะไรได้บ้าง

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

ข้อมูลดังกล่าวสามารถรองรับฟีเจอร์ที่ใช้งานได้จริงหลายอย่าง:

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

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

UPS Tracking API กับเว็บไซต์ UPS

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

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

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

สิ่งที่ต้องเตรียมก่อนส่งคำขอ

เตรียมรายการต่อไปนี้ก่อนเขียนการผสานรวม:

1. บัญชีนักพัฒนา UPS ใช้ UPS Developer Portal อย่างเป็นทางการเพื่อดู API ที่มีให้บริการและสร้างแอปพลิเคชัน
2. ข้อมูลรับรองแอปพลิเคชัน ชื่อข้อมูลรับรองและขั้นตอนการยืนยันตัวตนที่แน่นอนควรอ้างอิงจากเอกสาร UPS ปัจจุบัน อย่าวาง client secrets ไว้ในโค้ดเบราว์เซอร์ แอปพลิเคชันมือถือ ที่เก็บโค้ดสาธารณะ หรือหน้าที่ลูกค้ามองเห็น
3. หมายเลขติดตามพัสดุที่ถูกต้องสำหรับการทดสอบ ทดสอบกับการจัดส่งที่องค์กรของคุณได้รับอนุญาตให้เข้าถึง และหลีกเลี่ยงการเปิดเผยข้อมูลการจัดส่งส่วนบุคคลหรือเชิงพาณิชย์ในบันทึก
4. จุดเชื่อมต่อฝั่งเซิร์ฟเวอร์ โดยปกติบริการแบ็กเอนด์จะปลอดภัยกว่าการเรียกผู้ให้บริการขนส่งโดยตรงจากหน้าเว็บสาธารณะ เพราะสามารถเก็บข้อมูลรับรองไว้เป็นความลับและควบคุมปริมาณคำขอได้
5. แผนการจัดเก็บผลลัพธ์ ตัดสินใจว่าต้องการฟิลด์ใด จะเก็บไว้นานเท่าใด และจะเชื่อมโยงเหตุการณ์ของผู้ให้บริการขนส่งกับคำสั่งซื้อภายในอย่างไร

เวิร์กโฟลว์การผสานรวมสำหรับผู้เริ่มต้น

1. ยืนยันความต้องการทางธุรกิจ

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

หลีกเลี่ยงการร้องขอทุกฟิลด์ที่มีอยู่โดยไม่มีเหตุผล โมเดลข้อมูลที่เล็กกว่าจะดูแลรักษาได้ง่ายกว่า และมีโอกาสน้อยกว่าที่จะเปิดเผยข้อมูลที่ผู้ใช้ไม่จำเป็นต้องใช้

2. ลงทะเบียนแอปพลิเคชัน

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

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

3. ดำเนินการยืนยันตัวตน

การยืนยันตัวตนเป็นการพิสูจน์ว่าแอปพลิเคชันของคุณได้รับอนุญาตให้เรียกใช้บริการ ปฏิบัติตามวิธีการยืนยันตัวตน จุดเชื่อมต่อโทเค็น ข้อกำหนด scope และรูปแบบส่วนหัวที่ระบุในเอกสาร UPS ปัจจุบัน ถือว่า access tokens เป็นข้อมูลลับชั่วคราว และอย่าเขียนลงในบันทึกของแอปพลิเคชัน

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

4. ส่งคำขอติดตามพัสดุ

หลังจากยืนยันตัวตนแล้ว ให้ส่งคำขอโดยใช้การดำเนินการติดตามและรูปแบบตัวระบุที่ UPS ระบุ URL วิธี HTTP ส่วนหัว และโครงสร้างการตอบกลับที่แน่นอนควรอ้างอิงจากเอกสารอย่างเป็นทางการของ API เวอร์ชันที่คุณเลือก

คำขอเชิงแนวคิดมีลักษณะดังนี้:

POST /tracking-operation
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "trackingNumber": "YOUR_TRACKING_NUMBER"
}

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

5. ทำให้ผลลัพธ์เป็นมาตรฐาน

การตอบกลับจากผู้ให้บริการขนส่งไม่ได้เขียนด้วยภาษาที่ลูกค้าของคุณคาดหวังเสมอไป สร้างโมเดลเหตุการณ์ภายในที่มีฟิลด์คงที่ เช่น:

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

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

6. ตัดสินใจว่าจะเรียกดูข้อมูลอัปเดตอย่างไร

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

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

ข้อผิดพลาดทั่วไปและวิธีจัดการ

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

เมื่อใดควรใช้ Multi-Carrier API

การผสานรวม UPS โดยตรงอาจเป็นตัวเลือกที่เหมาะสมเมื่อการจัดส่งของคุณส่วนใหญ่ดำเนินการโดย UPS และทีมของคุณต้องการควบคุมการเชื่อมต่อกับผู้ให้บริการขนส่งโดยตรง ข้อแลกเปลี่ยนคือผู้ให้บริการขนส่งเพิ่มเติมแต่ละรายอาจต้องใช้รูปแบบการยืนยันตัวตน โครงสร้างข้อมูล นโยบายข้อผิดพลาด และกระบวนการบำรุงรักษาที่แตกต่างกัน

หากการดำเนินงานของคุณใช้ผู้ให้บริการขนส่งหลายราย บริการแบบหลายผู้ให้บริการสามารถลดจำนวนการผสานรวมแยกกันได้ 17TRACK's Tracking API ออกแบบมาสำหรับการติดตามการจัดส่งผ่านแอปพลิเคชัน และ เอกสารนักพัฒนาอย่างเป็นทางการ อธิบายรูปแบบการผสานรวมที่มีให้บริการ บริการนี้อาจคุ้มค่าที่จะประเมินเมื่อความต้องการที่แท้จริงไม่ใช่เพียงการติดตาม UPS แต่คือการมีชั้นการติดตามที่สอดคล้องกันสำหรับผู้ให้บริการขนส่งหลายราย

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

รายการตรวจสอบความพร้อมสำหรับใช้งานจริง

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

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

คำถามที่พบบ่อย

หากฉันติดตามพัสดุเพียงไม่กี่ชิ้น จำเป็นต้องใช้ API หรือไม่?

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

ฉันสามารถเรียก UPS Tracking API จากธีม Shopify หรือเบราว์เซอร์ได้หรือไม่?

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

Tracking API สามารถสร้างใบปะหน้าสำหรับการจัดส่งได้หรือไม่?

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

เหตุใดหมายเลขติดตามที่ถูกต้องจึงอาจส่งข้อมูลกลับมาเพียงเล็กน้อย?

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

ควรเลือก UPS โดยตรงหรือ Multi-Carrier Tracking API?

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

แหล่งข้อมูล

• UPS Developer Portal
• เอกสาร UPS Tracking API และแหล่งข้อมูลผลิตภัณฑ์
• 17TRACK Tracking API
• เอกสาร 17TRACK API