API gói đăng ký dựa trên số theo dõi Advanced Integrated Visibility cho phép người đăng ký Advanced Integrated Visibility liên kết số theo dõi với một dự án webhook bằng cách sử dụng điểm cuối API. Khả năng liên kết số theo dõi hỗ trợ hai phương thức xử lý:

• Liên kết số theo dõi – Đồng bộ trả về kết quả xử lý trong cùng một phản hồi HTTP. Tùy chọn này phù hợp nhất cho các ứng dụng yêu cầu xác nhận ngay lập tức khi liên kết số lượng nhỏ số theo dõi. 
• Liên kết số theo dõi – Không đồng bộ gửi yêu cầu để xử lý dưới nền và trả về ID công việc có thể dùng để truy xuất trạng thái và kết quả xử lý sau này. Tùy chọn này phù hợp nhất để xử lý các lô lớn số theo dõi. 

Chọn phương thức xử lý đáp ứng tốt nhất các yêu cầu về hiệu suất và khối lượng công việc của ứng dụng.

Lưu ý:

• Bạn phải có quyền truy cập của quản trị viên hoặc cộng tác viên để quản lý dự án Advanced Integrated Visibility của mình
• Để biết thêm thông tin về Advanced Integrated Visibility và các tính năng tương ứng, truy cập trang tài liệu Advanced Integrated Visibility.

API Gói đăng ký dựa trên số theo dõi Advanced Integrated Visibility mang lại những lợi ích sau:

• Bạn có thể dễ dàng liên kết, cập nhật và quản lý các số theo dõi cho dự án webhook Advanced Integrated Visibility bằng cách sử dụng các điểm cuối API.
• Liên kết nhiều số theo dõi trong một yêu cầu API thay vì xử lý riêng lẻ từng số theo dõi.
• Bạn có thể lựa chọn giữa xử lý đồng bộ để có kết quả ngay lập tức hoặc xử lý không đồng bộ cho các tác vụ theo lô lớn.

Sử dụng các điểm cuối sau để quản lý dự án Advanced Integrated Visibility:

• Liên kết số theo dõi – Đồng bộ: cho phép bạn liên kết các số theo dõi với một webhook và nhận trạng thái xử lý cuối cùng ngay trong cùng một phản hồi HTTP.
• Liên kết số theo dõi – Không đồng bộ: cho phép bạn liên kết các số theo dõi với một webhook và sử dụng jobId được trả về sau đó để kiểm tra trạng thái của công việc không đồng bộ hoặc tải xuống chi tiết bằng cách sử dụng điểm cuối liên quan:    
  • Trạng thái công việc dựa trên số theo dõi
  • Thông tin chi tiết về công việc dựa trên số theo dõi

Các API này có trên trang tổng quan dự án Advanced Integrated Visibility của bạn.

Bạn chỉ có thể truy cập các API này thông qua trang tổng quan dự án, như được thể hiện trong ảnh chụp màn hình ở trên.

Bảng dưới đây tóm tắt những điểm khác biệt giữa các điểm cuối Liên kết số theo dõi đồng bộ và không đồng bộ.
 

Sử dụng điểm cuối đồng bộ khi bạn cần xác nhận ngay đối với các lô có số lượng nhỏ các số theo dõi. Sử dụng điểm cuối không đồng bộ khi xử lý các lô lớn không yêu cầu phản hồi ngay.

Sử dụng điểm cuối này để liên kết một hoặc nhiều số theo dõi với một dự án webhook Advanced Integrated Visibility và nhận kết quả xử lý trong cùng một phản hồi HTTP.

Điểm cuối này dành cho các ứng dụng cần xác nhận ngay và hỗ trợ các yêu cầu chứa tối đa 150 số theo dõi.

Thông tin đầu vào bắt buộc: 

• subscriptionID
• trackingNumber

Lợi ích

Điểm cuối đồng bộ mang lại các lợi ích sau:

• Kết quả xử lý ngay lập tức
• Thông tin chi tiết về các trường hợp thành công và thất bại trong cùng một phản hồi
• Hỗ trợ tối đa 150 số theo dõi cho mỗi yêu cầu
• Xác thực yêu cầu và thực thi các quy tắc nghiệp vụ trước khi xử lý
• Mã lỗi có thể đọc được bằng máy và thông báo lỗi mang tính mô tả
• ID giao dịch để theo dõi yêu cầu và khắc phục sự cố

Điểm cuối Liên kết số theo dõi – Đồng bộ thực thi nhiều quy tắc xác thực, bao gồm:

• Yêu cầu subscriptionId phải hợp lệ và đang hoạt động
• Chỉ cho phép một subscriptionId cho mỗi yêu cầu
• Yêu cầu có trackingNumber
• Đảm bảo số theo dõi đáp ứng các yêu cầu về định dạng của FedEx, bao gồm giới hạn độ dài số theo dõi tối đa từ 6 đến 22 chữ số

Các phản hồi lỗi tuân theo một cấu trúc nhất quán với errors[] chứa code và message để dễ dàng phân tích.

"errors": [

{

"code": "ERROR.CODE",

"message": "Thông báo lỗi mang tính mô tả"

}

Điểm cuối Liên kết số giao dịch – Đồng bộ hỗ trợ xử lý thành công một phần. Khi một vài số theo dõi xử lý không thành công, API đồng bộ vẫn trả về mã lỗi 200 OK và hiển thị nội dung sau:

• failedTrackingNumbers
• Một thông báo mô tả

{

"transactionId":

   "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

   "output": {

      "failedTrackingNumbers":

         [ "XXXXX",

         " YYYYY"

         ],

      "message": "Các số theo dõi dưới đây không tải lên được do lỗi xác thực hoặc lỗi hệ thống"

      }

    }

Xem các phần quy tắc nghiệp vụ để biết thêm chi tiết và quy tắc.

Sử dụng điểm cuối này để gửi một hoặc nhiều số theo dõi đã đăng ký để xử lý dưới nền.

Yêu cầu trả về một ID công việc mà bạn có thể sử dụng với điểm cuối Trạng thái công việc số theo dõi để giám sát quá trình xử lý và sử dụng với điểm cuối Chi tiết công việc số theo dõi để tải xuống kết quả xử lý sau khi công việc hoàn thành.

Thông tin đầu vào bắt buộc:

• Hành động
• Chi tiết số theo dõi

Bạn có thể liên kết tối đa 1.000 số theo dõi trong một yêu cầu.

Lợi ích

Điểm cuối không đồng bộ mang lại những lợi ích sau:

• Hỗ trợ gửi các lô lớn lên đến 1.000 số theo dõi
• Cho phép xử lý các yêu cầu kéo dài trong nền
• Cho phép giám sát trạng thái công việc và tải xuống báo cáo xử lý.
• Loại bỏ mối lo ngại về thời gian chờ yêu cầu đối với khối lượng công việc lớn

Dùng điểm cuối này để lấy trạng thái của một công việc không đồng bộ (một hoặc nhiều yêu cầu liên tiếp trong hàng chờ) hoặc trạng thái của tất cả các công việc đã gửi.

Thông tin đầu vào cần có cho yêu cầu này là:

• jobID – Cho biết ID công việc mà bạn định truy xuất trạng thái.

Lưu ý: ID công việc là thông tin đầu vào tùy chọn cho điểm cuối này. Nếu bạn không chỉ định ID công việc, bạn sẽ nhận được trạng thái của tất cả các công việc đã gửi.

Phản hồi thành công cho yêu cầu này sẽ trả về jobID, trạng thái công việc hiện tại, cũng như thời gian tạo và hoàn tất công việc. Phản hồi sẽ hiển thị trạng thái hiện tại của công việc. Ngoài ra, phản hồi cũng sẽ chứa các thông báo thành công, thông báo lỗi hoặc cảnh báo để người dùng xem và khắc phục sự cố nếu có.

• Nếu trạng thái công việc hiển thị là ĐÃ HOÀN TẤT thì có nghĩa là tất cả các số theo dõi đã được xác thực và xử lý thành công.
  • Trạng thái ĐÃ HOÀN TẤT ngụ ý rằng số theo dõi đã được xác thực và xử lý thành công chứ không ngụ ý rằng tất cả số theo dõi đều đã được thêm thành công vào dự án Advanced Integrated Visibility.
  • Đối với các công việc có nhiều số theo dõi, trạng thái có thể được xem là ĐÃ HOÀN TẤT ngay cả khi một vài số theo dõi không liên kết được với dự án và các số theo dõi khác thì liên kết được. Để xác nhận trạng thái của từng số theo dõi trong yêu cầu liên kết ban đầu, hãy tải xuống báo cáo theo lô.

Lưu ý: Nếu trạng thái công việc hiển thị là KHÔNG THÀNH CÔNG, điều đó có nghĩa là do nhiều lý do/lỗi nghiêm trọng khác nhau, yêu cầu đã không thể được xử lý và người dùng phải thử lại.

Bảng dưới đây hiển thị các trạng thái công việc và mô tả tương ứng:

Dùng điểm cuối này để tải xuống báo cáo JSON cho công việc không đồng bộ đang ở trạng thái ĐÃ HOÀN TẤT.

Thông tin đầu vào cần thiết liên kết với yêu cầu này là:

• jobID – Cho biết ID công việc mà bạn định truy xuất trạng thái. ID công việc là bắt buộc đối với điểm cuối này.

Lưu ý:

• Bạn chỉ có thể tải xuống một báo cáo công việc không đồng bộ tại một thời điểm.
• Nếu công việc chưa ở trạng thái ĐÃ HOÀN TẤT mà bạn lại cố tải báo cáo xuống thì thông báo lỗi sẽ hiển thị.

Phản hồi thành công cho yêu cầu này sẽ cung cấp cho bạn báo cáo về công việc ở định dạng JSON.

Quy tắc nghiệp vụ chung

• Không có giới hạn về tổng số lượng số theo dõi có thể liên kết với một dự án Advanced Integrated Visibility.
• Các số theo dõi được liên kết với một dự án Advanced Integrated Visibility sẽ bị hủy liên kết 40 ngày sau khi được liên kết thành công với webhook.
• Thông tin theo dõi bảo mật, như địa chỉ người nhận, chữ ký người nhận và thông tin giao hàng nhạy cảm, không có sẵn qua API Gói đăng ký số theo dõi.

Quy tắc nghiệp vụ cho điểm cuối đồng bộ

• Tối đa 150 số theo dõi cho mỗi yêu cầu.
• Tất cả các số theo dõi phải sử dụng cùng một subscriptionId.
• Gói đăng ký webhook Advanced Integrated Visibility được chỉ định phải hợp lệ và đang hoạt động.
• Các yêu cầu có thời gian chờ là 30 giây.

Quy tắc nghiệp vụ cho điểm cuối không đồng bộ

• Tối đa 1.000 số theo dõi cho mỗi yêu cầu.
• Trạng thái công việc và chi tiết công việc cho một yêu cầu không đồng bộ được lưu giữ trong 90 ngày sau khi các số theo dõi được liên kết thành công với webhook Advanced Integrated Visibility.