Phương thức tối ưu về tích hợp API FedEx

Đây là hướng dẫn tham khảo nhanh nhằm giúp người dùng API hiểu những cách thức cải thiện trải nghiệm tích hợp với FedEx và đảm bảo chất lượng của giải pháp tích hợp về mặt thiết kế, tốc độ và tính bảo mật.

Để tích hợp hiệu quả với API FedEx, nhà phát triển nên tuân theo các phương thức tích hợp tối ưu sau:

URI API

• Có các URI API riêng biệt cho thử nghiệm và sản xuất. 
• Nhà phát triển nên sử dụng các URI thử nghiệm trong phát triển và thử nghiệm tích hợp và dùng URI sản xuất trong sản xuất.

Dưới đây là danh sách URI API:

Thử nghiệm: https://apis-sandbox.fedex.com/

Sản xuất: https://apis.fedex.com/

Quản lý thông tin xác thực

• Mã API và Mã khóa bí mật

• Mã API và Mã khóa bí mật được sử dụng để nhận dạng ứng dụng của bạn và cần được sử dụng trong yêu cầu mã thông báo OAuth.

1. Mã API và Mã khóa bí mật của bạn phải được đảm bảo bảo mật. Không phân phối Mã API hoặc Mã khóa bí mật qua email hoặc mã được phân phối bao gồm JavaScript phía máy khách.
2. Ứng dụng của bạn sẽ bị xâm phạm nếu Mã API hoặc Mã khóa bí mật bị đánh cắp. Nếu bạn nghi ngờ thông tin xác thực của bạn bị đánh cắp hoặc bị xâm phạm, vui lòng tạo lại Mã khóa bí mật ngay lập tức.
3. Tránh ghi lại thông tin nhạy cảm như Mã khóa bí mật.

• Không cố định Mã API và Mã khóa bí mật trong mã lập trình của bạn.
• Ứng dụng của bạn phải có khả năng cập nhật động Mã API và Mã khóa bí mật.
• Thông tin xác thực của khách hàng phải được lưu trữ trong kho lưu trữ/nơi an toàn để không bị xâm phạm.

• Mã thông báo OAuth

• Bạn chỉ nên lưu trữ mã thông báo truy cập trên máy chủ ứng dụng web và không được để lộ trên trình duyệt.
• Không lập trình cố định mã thông báo trong ứng dụng.
• Bảo mật mã thông báo truy cập để tránh bị xâm phạm.
• Tránh thực hiện nhiều lệnh gọi đến API mã thông báo OAuth để lấy mã thông báo truy cập mới. Bạn nên lưu bộ nhớ đệm mã thông báo truy cập cho đến khi quan sát thấy mã lỗi HTTP 401. Khi đó, hãy tạo lại mã thông báo OAuth.
• Không để lộ mã thông báo cho người dùng cuối hay cho ứng dụng.
• Sử dụng HTTPS cho mọi giao dịch API.

Thực tế lập trình

• Để duy trì tuân thủ giao thức truyền thông mã hóa dữ liệu mới nhất và bảo mật nhất, bạn nên sử dụng Bảo mật tầng giao vận (TLS) phiên bản 1.2 trở lên.
• Nhớ đặt đúng tiêu đề API cần thiết cho từng yêu cầu API. Bạn sẽ tìm thấy thông tin tiêu đề dưới mỗi trang tài liệu về API. 
• ’Content-Type’ trong HTTP POST phải là ‘application/json’.
• Vui lòng tham khảo mã lập trình mẫu để bắt đầu với từng API. Mỗi điểm cuối API đi kèm với một số đoạn mã mẫu sẽ giúp bạn hiểu các phần tử, định dạng cần thiết cũng như các chi tiết khác.
• Khi người dùng hoặc nhà phát triển gửi nhiều chữ số thập phân trong giá trị, có thể gây ra các lỗi lạ. Trọng lượng và giá trị tiền tệ/số tiền chỉ được có hai chữ số thập phân rõ ràng. Kích thước – chẳng hạn như chiều dài, chiều rộng và chiều cao – không được dùng số thập phân.

Ví dụ: Trọng lượng: 45,26, giá trị tiền tệ/số tiền: 100,52, chiều dài: 10, chiều rộng: 25, chiều cao: 15.

• Tránh gửi các phần tử rỗng.

Ví dụ: “Streetlines”:””

• Chỉ gửi những dữ liệu cần thiết để xử lý yêu cầu.

Ví dụ: đối với lô hàng nội địa của Hoa Kỳ, tránh gửi hóa đơn thương mại và dữ liệu hàng hóa chỉ cần thiết cho lô hàng quốc tế.

• Khi phát triển, hãy xác định cách ứng phó nếu phần tử trả lời không bắt buộc, chẳng hạn như giá cước, không được trả về. Đánh giá việc phản hồi giao dịch cho các phần tử còn thiếu trước khi sử dụng dữ liệu.

Ví dụ: có thể gửi gói hàng đi nếu phần tử giá cước không hoạt động. Thử nghiệm việc phản hồi giao dịch cho các phần tử còn thiếu trước khi sử dụng dữ liệu.

• Nói chung, hãy tránh đưa các phần phụ thuộc cố định vào trong tích hợp API FedEx, tùy trường hợp áp dụng.
• Để giảm độ trễ và có kết quả chính xác, bạn nên sử dụng các cách sau:
  
  • Lọc - Sử dụng công cụ này để thu hẹp phạm vi tìm kiếm với các thông số bạn cần.
  • Sắp xếp - Sử dụng công cụ này để sắp xếp các kết quả theo một thông số nhất định theo thứ tự tăng dần hoặc giảm dần.
• Kiểm tra các trường bắt buộc – chẳng hạn như mã bưu chính và trọng lượng gói hàng – có dữ liệu trước khi gửi giao dịch. Kiểm tra dữ liệu phù hợp với lĩnh vực. Làm như vậy sẽ giảm thiểu lỗi giao dịch.
  

Ví dụ: đối với mã bưu chính của Hoa Kỳ, hãy xác minh rằng bạn chỉ nhập số theo định dạng mã bưu chính gồm 5 chữ số hoặc ZIP+4 vào trường.

• Để tránh tác động bất lợi đến tính sẵn có và độ tin cậy của hệ thống FedEx:
  
  • Không chạy thử nghiệm hiệu suất trong môi trường thử nghiệm hoặc sản xuất.
  • Duy trì logic lập trình tại chỗ để tránh cho cùng một giao dịch bị thất bại nhiều lần.
• Giới hạn điều chỉnh được đặt thành 1400 giao dịch trong 10 giây. Nếu đạt đến giới hạn này trong vài giây đầu tiên, hệ thống sẽ trả về mã lỗi HTTP 429 Quá nhiều yêu cầu và bạn sẽ bị hạn chế giao dịch cho đến khi hết 10 giây; sau đó giao dịch sẽ tiếp tục lại.
  

Ví dụ: nếu chúng tôi nhận được 1400 yêu cầu trong bốn giây đầu tiên, hệ thống sẽ trả về mã lỗi HTTP 429 Quá nhiều yêu cầu - ‘Chúng tôi nhận được quá nhiều yêu cầu trong khoảng thời gian ngắn. Vui lòng chờ một lúc rồi thử lại.' và bạn sẽ bị hạn chế giao dịch trong sáu giây tiếp theo rồi mới tiếp tục lại.

• Không lập trình cố định cho các quy tắc kinh doanh như loại dịch vụ, loại gói hàng, giới hạn trọng lượng, v.v. cho các lô hàng vì các thông tin này có thể thay đổi.

Lỗi xử lý

Mỗi phản hồi API sẽ chứa mã trạng thái HTTP và trọng tải phản hồi. Một số phản hồi sẽ đi kèm với lỗi, cảnh báo hoặc ghi chú, tùy trường hợp áp dụng. Cảnh báo và ghi chú không phải là dấu hiệu của lỗi; tuy nhiên, bạn nên ghi lại và kiểm tra thông báo lỗi hoặc cảnh báo. Xử lý lỗi đúng cách sẽ đảm bảo rằng việc tích hợp với FedEx diễn ra suôn sẻ và có thể giúp tránh tình trạng hỏng.

Mã trạng thái HTTP

Giá cước

• Có hai cách để xem báo giá:
  
  • Giá cước cho một serviceType cụ thể - Kết quả sẽ được lọc theo giá trị serviceType được chỉ định. Cách này sẽ làm giảm kích thước của câu trả lời và giảm thời gian phản hồi giao dịch.
    

    Ví dụ: STANDARD_OVERNIGHT

  • So sánh giá cước – Nếu không có serviceType nào được chỉ định, hệ thống sẽ trả về tất cả các dịch vụ có thể áp dụng và giá cước tương ứng.
• Sử dụng API Tính sẵn có của dịch vụ để xác định các dịch vụ, tùy chọn về gói hàng và dịch vụ đặc biệt dành cho một cặp nơi gửi hàng - nơi nhận hàng nhất định, bỏ qua serviceType và tùy chọn gói hàng trong yêu cầu Giá cước.
  

  Ví dụ: STANDARD_OVERNIGHT (trong số các loại dịch vụ khác) không áp dụng được giữa tất cả các mã bưu chính.

• Để áp dụng dịch vụ đặc biệt cho một lô hàng, bạn phải đưa vào loại dịch vụ đặc biệt và chi tiết của loại dịch vụ đó. 
  
  • Lưu ý: Một số dịch vụ đặc biệt không có chi tiết.
• Xem Tài liệu về API Giá cước.

Vận chuyển

• Sử dụng API Tính sẵn có của dịch vụ để xác định các dịch vụ sẵn có cho một cặp nơi gửi hàng - nơi nhận hàng nhất định, bỏ qua tùy chọn loại dịch vụ và gói hàng trong yêu cầu Vận chuyển.
• Để áp dụng dịch vụ đặc biệt cho một lô hàng, bạn phải đưa vào loại dịch vụ đặc biệt và chi tiết của loại dịch vụ đó.
  
  • Lưu ý: Một số dịch vụ đặc biệt không có chi tiết.
• Thực hiện đóng FedEx Ground vào cuối ngày giao hàng trước khi có người đến lấy lô hàng.
  
• Xem Tài liệu về API Vận chuyển.
  

Theo dõi

• Giới hạn số lượng số theo dõi trong một yêu cầu theo dõi là 30. Cách này sẽ làm giảm kích thước của câu trả lời và giảm thời gian phản hồi giao dịch.
• Giới hạn số lần theo dõi gói hàng tùy theo nhu cầu kinh doanh.
• Khi theo dõi hàng loạt, hãy xóa bất kỳ gói hàng nào trả về trạng thái theo dõi là "đã giao".
• Xem tài liệu về API Theo dõi.

Xác thực địa chỉ

• FedEx cung cấp tính năng Xác thực địa chỉ ở dạng gợi ý và không phải là quyết định cuối cùng. Người dùng cuối cần dựa vào nhu cầu kinh doanh và dữ liệu được cung cấp để đưa ra quyết định cuối cùng về việc địa chỉ có thể sử dụng hay không. Phải có quy trình để xử lý các địa chỉ không thể xác thực để vẫn có thể xử lý các đơn hàng.
• Để đảm bảo trải nghiệm vận chuyển tốt hơn, đừng để quá trình vận chuyển phụ thuộc vào các dịch vụ không bắt buộc như Xác thực địa chỉ.

Ví dụ: nếu API Xác thực địa chỉ không thể sử dụng tại thời điểm nhập đơn hàng hoặc gửi hàng, phải có phương án dự phòng để hoàn tất lô hàng.

• Xem Tài liệu về API Xác thực địa chỉ.
  

Tìm kiếm địa điểm FedEx

• Thu hẹp phạm vi tìm kiếm bằng cách cung cấp các thuộc tính cụ thể (ví dụ: loại địa điểm, dịch vụ được cung cấp, v.v.) để có các tùy chọn địa điểm phù hợp và thời gian phản hồi nhanh hơn.
• Xem tài liệu về API tìm kiếm địa điểm FedEx.
  

Yêu cầu lấy hàng

• Không nhập giờ sẵn sàng đã qua, ngày đã qua hoặc ngày quá xa trong tương lai để lên lịch lấy hàng.
• Không cho phép lấy hàng ẩn danh.
  
• Xem Tài liệu về API Yêu cầu lấy hàng.
  

Tính sẵn có của dịch vụ

• Để xem kết quả về nhiều công ty kinh doanh như FedEx Express (FDXE), FedEx Ground (FDXG), FedEx Freight (FXFR) và FedEx Ground® Economy, hãy bỏ thành phần carrierCodes hoặc gửi từng yêu cầu về tính sẵn có của dịch vụ vì không thể xác định được nhiều mã hãng vận tải.
• Vui lòng đảm bảo bạn được phê duyệt trước cho các tấm nâng hàng rời nặng 151 lb trở lên hoặc các tấm nâng hàng vượt quá 2.200 lb.
  
• Nếu bạn chỉ định SATURDAY_DELIVERY cho các tùy chọn biến đổi, bạn sẽ nhận được cả tùy chọn giao hàng thứ Bảy và tùy chọn thông thường cho tất cả các dịch vụ có tùy chọn giao hàng thứ Bảy. Không chỉ định SATURDAY_DELIVERY cho dịch vụ đặc biệt, nếu không API này sẽ chỉ trả về mọi tùy chọn giao hàng thứ Bảy có thể áp dụng.
• Xem Tài liệu về API Tính sẵn có của dịch vụ.

Hỗ trợ khách hàng

Nếu bạn có thắc mắc hoặc cần hỗ trợ, chúng tôi luôn sẵn sàng trợ giúp! Vui lòng truy cập trang Hỗ trợ để xem tài nguyên và thông tin về các cách liên hệ với chúng tôi.