แนวปฎิบัติที่ดีที่สุดในการผสานรวม FedEx API

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

เพื่อให้ผสานรวมเข้ากับ FedEx API ได้อย่างมีประสิทธิภาพ ผู้พัฒนาควรปฏิบัติตามแนวปฏิบัติที่ดีที่สุดเหล่านี้

URI สำหรับ API

• URI สำหรับ API ที่ใช้ในการทดสอบและการใช้งานจริงจะเป็นคนละส่วน 
• ผู้พัฒนาควรใช้ URI การทดสอบในการพัฒนาและทดสอบการผสานรวม และใช้ URI การใช้งานสำหรับการใช้งานจริง

URI สำหรับ API ได้แก่

การทดสอบ: https://apis-sandbox.fedex.com/

การใช้งานจริง: https://apis.fedex.com/

การจัดการข้อมูลประจำตัว

• รหัส API และรหัสลับ

• รหัส API และรหัสลับของคุณใช้เพื่อระบุแอปพลิเคชัน และจำเป็นต้องใช้สำหรับการขอโทเค็น OAuth

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

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

• โทเค็น OAuth

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

แนวทางปฏิบัติในการเขียนโค้ด

• เพื่อเป็นการปฏิบัติให้สอดคล้องกับโปรโตคอลการสื่อสารสำหรับการเข้ารหัสข้อมูล จึงขอแนะนำให้ใช้ Transport Layer Security (TLS) เวอร์ชัน 1.2 ขึ้นไป
• อย่าลืมตั้งส่วนหัวของ API ที่จำเป็นสำหรับคำขอ API แต่ละรายการให้ถูกต้อง โดยคุณจะพบข้อมูลส่วนหัวที่ด้านล่างของหน้าเอกสาร API แต่ละหน้า 
• ค่า ’Content-Type’ ใน HTTP POST ควรเป็น ‘application/json’
• กรุณาดูโค้ดตัวอย่างเพื่อเริ่มต้นใช้งาน API แต่ละส่วน แต่ละปลายทางของ API จะมีตัวอย่างอยู่สองสามข้อที่จะช่วยให้คุณเข้าใจว่าอิลิเมนต์ รูปแบบ และรายละเอียดอื่นๆ ที่จำเป็นนั้นมีอะไรบ้าง
• เมื่อผู้ใช้หรือผู้พัฒนาใส่ทศนิยมหลายตำแหน่งลงในค่าต่างๆ อาจทำให้เกิดความผิดพลาดของข้อมูลได้ ในส่วนของมูลค่า/จำนวนสกุลเงิน ต้องระบุเป็นทศนิยมสองตำแหน่งเท่านั้น ขนาด – เช่น ความยาว ความกว้าง และความสูง – ไม่รองรับการระบุเลขทศนิยม

ตัวอย่าง: น้ำหนัก: 45.26, มูลค่า/จำนวนสกุลเงิน: 100.52, ความยาว: 10, ความกว้าง: 25, ความสูง:15

• หลีกเลี่ยงการส่งอิลิเมนต์ว่าง

ตัวอย่าง: "บรรทัดที่อยู่":""

• ให้ส่งเฉพาะข้อมูลที่จำเป็นต่อการประมวลผลคำขอเท่านั้น

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

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

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

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

ตัวอย่างเช่น หากเป็นรหัสไปรษณีย์ในประเทศสหรัฐอเมริกา ให้ตรวจสอบว่าข้อมูลในฟิลด์ได้ระบุเป็นตัวเลขทั้งหมด และอยู่ในรูปแบบของรหัสไปรษณีย์ 5 หลักหรือในรูปแบบรหัสไปรษณีย์ 5 หลัก + หมายเลข 4 หลักแล้ว

• เพื่อป้องกันไม่ให้เกิดผลกระทบที่ไม่พึงประสงค์ต่อความพร้อมและความเชื่อถือได้ของระบบ FedEx จะต้อง:
  
  • ไม่ดำเนินการทดสอบประสิทธิภาพในระบบทดสอบหรือระบบใช้งานจริง
  • ใช้ตรรกะการเขียนโค้ดเพื่อป้องกันไม่ให้การทำรายการเดิมล้มเหลวซ้ำกันหลายครั้ง
• การจำกัดปริมาณการส่งคำขอกำหนดไว้ที่ 1400 รายการใน 10 วินาที หากถึงขีดจำกัดนี้ในสองสามวินาทีแรก จะมีการส่งกลับรหัสข้อผิดพลาด HTTP 429 คำขอมากเกินไป และการทำรายการจะถูกจำกัดจนกว่าจะครบ 10 วินาที จากนั้นจึงจะดำเนินการทำรายการต่อได้
  

ตัวอย่างเช่น หากเราได้รับคำขอจำนวน 1400 รายการใน 4 วินาทีแรก ระบบจะส่งรหัสข้อผิดพลาด HTTP 429 คำขอมากเกินไป - ‘เราได้รับคำขอมากเกินไปในระยะเวลาสั้นๆ กรุณารอสักครู่แล้วลองใหม่อีกครั้ง’ จากนั้นการทำรายการจะถูกจำกัดเป็นเวลา 6 วินาทีถัดไป แล้วจึงจะดำเนินการทำรายการต่อ

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

การจัดการข้อผิดพลาด

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

รหัสสถานะ HTTP

อัตราค่าบริการ

• การขอรับอัตราค่าบริการมี 2 วิธี:
  
  • อัตราค่าบริการสำหรับประเภทบริการ (serviceType) เฉพาะ - ระบบจะกรองผลลัพธ์ตามค่า serviceType ที่ระบุ วิธีนี้จะลดขนาดของการตอบกลับ และลดเวลาที่ใช้ในการตอบกลับสำหรับการทำรายการ
    

    ตัวอย่าง: STANDARD_OVERNIGHT

  • บริการที่สามารถเลือกใช้ได้ – หากไม่ระบุ serviceType บริการที่สามารถใช้ได้และอัตราค่าบริการของบริการดังกล่าวจะถูกส่งกลับทั้งหมด
• ใช้ API สำหรับความพร้อมในการให้บริการ เพื่อระบุว่าบริการ ตัวเลือกบรรจุภัณฑ์ และบริการพิเศษใดที่พร้อมให้บริการสำหรับคู่ต้นทาง-ปลายทางที่กำหนด และส่งประเภทบริการและตัวเลือกบรรจุภัณฑ์มาในคำขออัตราค่าบริการ
  

  ตัวอย่างเช่น STANDARD_OVERNIGHT (เช่นเดียวกับบริการอื่นๆ) ไม่พร้อมให้บริการในพื้นที่ระหว่างต้นทาง-ปลายทางตามรหัสไปรษณีย์ที่กำหนด

• จะต้องระบุประเภทบริการพิเศษและรายละเอียดของบริการพิเศษที่จะใช้สำหรับการจัดส่ง 
  
  • หมายเหตุ: บริการพิเศษบางประเภทไม่มีรายละเอียด
• ดู เอกสาร API สำหรับอัตราค่าบริการ

ทำการส่ง

• ใช้ API ความพร้อมในการให้บริการเพื่อระบุว่าบริการใดที่พร้อมให้บริการสำหรับคู่ต้นทาง-ปลายทางที่กำหนด และส่งประเภทบริการและตัวเลือกบรรจุภัณฑ์มาในคำขอการจัดส่ง
• จะต้องระบุประเภทบริการพิเศษและรายละเอียดของบริการพิเศษที่จะใช้สำหรับการจัดส่ง
  
  • หมายเหตุ: บริการพิเศษบางประเภทไม่มีรายละเอียด
• ปิดการทำงานสำหรับ FedEx Ground เมื่อสิ้นสุดเวลาทำการจัดส่งก่อนที่จะมีการรับพัสดุ
  
• ดู เอกสาร API สำหรับการจัดส่ง
  

ติดตามสถานะพัสดุ

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

การตรวจสอบที่อยู่

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

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

• ดู เอกสาร API สำหรับการตรวจสอบที่อยู่
  

ค้นหาศูนย์บริการ FedEx

• จำกัดการค้นหาให้แคบลงด้วยการระบุคุณลักษณะเฉพาะ (เช่น ประเภทศูนย์บริการ บริการที่นำเสนอ เป็นต้น) เพื่อให้ได้รับตัวเลือกสถานที่ที่เหมาะสมและได้รับการตอบกลับรวดเร็วยิ่งขึ้น
• ดูเอกสาร API สำหรับการค้นหาศูนย์บริการ FedEx
  

คำขอรับพัสดุ

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

ความพร้อมในการให้บริการ

• เพื่อให้ได้ผลลัพธ์สำหรับบริษัทที่ดำเนินงานต่างๆ เช่น FedEx Express (FDXE), FedEx Ground (FDXG), FedEx Freight (FXFR) และ FedEx Ground® Economy ให้ละองค์ประกอบ carrierCodes หรือส่งคำขอสำหรับความพร้อมในการให้บริการแยกต่างหาก เนื่องจากไม่สามารถระบุรหัสผู้ให้บริการขนส่งแบบหลายรายการได้
• กรุณาตรวจสอบให้แน่ใจว่าคุณได้รับการอนุมัติล่วงหน้าสำหรับสกิดน้ำหนัก 151 ปอนด์ ขึ้นไป หรือสกิดที่น้ำหนักเกิน 2,200 ปอนด์แล้ว
  
• หากคุณระบุทางเลือกตัวแปรเป็น SATURDAY_DELIVERY สำหรับบริการทั้งหมดที่มีตัวเลือกการจัดส่งในวันเสาร์ คุณจะได้รับทั้งตัวเลือกการจัดส่งในวันเสาร์และทางเลือกทั่วไป อย่าระบุ SATURDAY_DELIVERY สำหรับบริการพิเศษ มิฉะนั้นระบบจะคืนค่าเฉพาะตัวเลือกการจัดส่งในวันเสาร์ที่สามารถใช้ได้เท่านั้น
• ดู เอกสาร API สำหรับความพร้อมในการให้บริการ

แผนกบริการลูกค้า

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