Thông Báo Quan Trọng: Hướng Dẫn Cập Nhật Định Dạng URL Trang Thanh Toán và Đơn Hàng

Sau:

https://{store domain}/checkouts/{checkoutToken}

Ví dụ 1: Xác định loại trang

Sai:

// Bị lỗi sau khi thay đổi: regex cố định đoạn số đầu tiên
if (/^\/\d+\/checkouts\//.test(location.pathname)) { /* ... */ }
if (location.pathname.split('/')[2] === 'checkouts') { /* ... */ }

Khuyến nghị:

// Tương thích với cả định dạng cũ và mới: chỉ kiểm tra đoạn "checkouts"
// mà không quan tâm đoạn đứng trước nó là gì
const isCheckoutPage = /(^|\/)checkouts\/[^/]+/.test(location.pathname);
const isOrderPage    = /(^|\/)orders\/[^/]+/.test(location.pathname);

Ví dụ 2: Lấy storeId

Sai:

// Sau khi thay đổi, đoạn này lấy được "checkouts" — không báo lỗi nhưng giá trị sai
const storeId = location.pathname.split('/')[1];

Khuyến nghị:

// Lấy từ ngữ cảnh được nền tảng tiêm vào (trường chính xác tùy thuộc vào thời điểm chạy)
const storeId = window.Shopline?.storeId;
 
// Ứng dụng Open Platform: sử dụng trường storeId từ ngữ cảnh cài đặt app / phản hồi API

Ví dụ 3: Tạo liên kết

Sai:

// Tự xây dựng đường dẫn (không còn cách xây dựng thủ công nào hoạt động nữa)
const url = `https://${domain}/${storeId}/checkouts/${token}`;

Khuyến nghị:

// Sử dụng URL đầy đủ trả về từ API Open Platform, và chuyển hướng trực tiếp
const url = response.checkoutUrl;

Liên kết do nền tảng trả về luôn phản ánh định dạng hiện đang hợp lệ cho cửa hàng đó, bạn không cần tự xác định trạng thái chuyển đổi. Nếu bạn cần tạo liên kết cho kịch bản mà API hiện tại chưa hỗ trợ, hãy tham khảo tài liệu Open Platform hoặc gửi yêu cầu hỗ trợ Open Platform.

Ví dụ 4: Cấu hình chuyển hướng 301

Cấu hình gốc:

// Cấu hình "Chuyển hướng từ" hoặc "Chuyển hướng đến" gốc
/example storeId/checkouts

Cấu hình mới cần thêm: 

// Thêm cấu hình tương ứng cho định dạng mới
/checkouts

5. Danh sách kiểm tra tự kiểm tra

Thực hiện ba bước dưới đây để tìm kiếm trong mã nguồn và xác nhận từng mục. Việc tự kiểm tra chỉ hoàn tất khi mọi mục đã được xác nhận.

Bước 1: Tìm kiếm từ khóa

checkouts        orders          thank_you       stock_problems
processing       overload        checkoutToken   orderSeq        storeId

Bước 2: Tìm kiếm mẫu (Regex)

\/\d+\/checkouts        # Đoạn số cứng + checkouts
\/\d+\/orders           # Đoạn số cứng + orders
:storeId\/checkouts     # Cú pháp mẫu tuyến đường
\{storeId\}\/checkouts  # Cú pháp chuỗi mẫu
%s\/checkouts           # Cú pháp chuỗi định dạng phía backend
pathname.*split         # Lấy đoạn đường dẫn theo chỉ số
pathname.*match         # So khớp regex đường dẫn
location\.pathname      # Bất kỳ việc sử dụng pathname nào

Bước 3: Xác nhận từng mục

• Tất cả các kiểm tra loại trang đã được cập nhật để hỗ trợ cả định dạng cũ và mới
• storeId không còn được phân tích từ đường dẫn URL
• checkoutToken / orderSeq không còn được trích xuất từ đường dẫn URL
• checkout_url chỉ được sử dụng cho chuyển hướng, không còn phân tích để lấy giá trị
• Đường dẫn trang Checkout/order không còn được xây dựng thủ công — thay vào đó sử dụng URL đầy đủ từ API Open Platform
• Nhóm trang và quy tắc đường dẫn mục tiêu chuyển đổi trong bảng điều khiển phân tích bên thứ ba (ví dụ, GA) đã được cập nhật

6. Câu hỏi thường gặp

Q1: Liên kết cũ có ngừng hoạt động không?

Không. Liên kết theo định dạng cũ sẽ tiếp tục tự động chuyển hướng đến URL mới và vẫn có thể truy cập lâu dài, bạn không cần thay thế thủ công bất kỳ liên kết nào đã gửi, và không cần di chuyển dữ liệu lịch sử.

Q2: Khách hàng của tôi có nhận thấy cập nhật này không?

Không. Truy cập, thanh toán và điều hướng trang của khách hàng bình thường không bị ảnh hưởng, cập nhật này chỉ thay đổi cấu trúc kỹ thuật của URL.

Q3: Điều gì xảy ra nếu tôi không hoàn thành việc thích ứng trước hạn chót?

Sau ngày 19 tháng 9 năm 2026, định dạng URL sẽ được chuyển hoàn toàn sang định dạng mới, và SHOPLINE không thể hoàn nguyên. Nếu mã tùy chỉnh, ứng dụng hoặc hệ thống bên thứ ba của bạn vẫn phụ thuộc vào định dạng URL cũ để phân tích dữ liệu, bạn có thể gặp sự cố xử lý dữ liệu hoặc chức năng, và những lỗi này thường xảy ra âm thầm, không báo lỗi hoặc trang trắng. Chúng tôi khuyến nghị kiểm tra tích hợp và hoàn thành thích ứng càng sớm càng tốt.

Q4: Tôi có gặp cả hai định dạng cùng lúc trong quá trình triển khai không?

Có. Các cửa hàng chuyển đổi theo từng đợt, vì vậy các cửa hàng khác nhau có thể ở các định dạng khác nhau vào các thời điểm khác nhau. Hãy xây dựng thích ứng của bạn để hỗ trợ cả hai định dạng cùng lúc, thay vì xem đó là kiểm tra một hoặc khác.

Q5: Nếu liên kết tôi nhận được từ API không khớp với trạng thái chuyển đổi hiện tại của cửa hàng thì sao?

Chỉ cần sử dụng như hiện tại. Liên kết trả về bởi nền tảng luôn trỏ đến trang hiện đang hợp lệ cho cửa hàng đó. Ngay cả khi định dạng có vẻ không nhất quán với trạng thái chuyển đổi, nền tảng sẽ tự động xử lý chuyển hướng — bạn sẽ không gặp lỗi 404.

Q6: Tôi cần storeId, checkoutToken hoặc orderSeq, nhưng không lấy được từ URL. Tôi nên làm gì?

Kiểm tra tài liệu Open Platform cho điểm cuối liên quan. Với các kịch bản không được đề cập, hãy gửi vé hỗ trợ Open Platform.

Q7: Đường dẫn điểm cuối OpenAPI có thay đổi không?

Không. Cập nhật này chỉ thay đổi liên kết trang hướng đến người mua; đường dẫn API không bị ảnh hưởng.

Q8: Trường checkoutUrl trong phản hồi API có thay đổi không?

Có. Nó sẽ thay đổi từ việc bao gồm storeId sang không còn bao gồm nữa.

Câu 9: Trang đăng ký lại có thay đổi không?

Không. Đường dẫn của trang đó chưa bao giờ bao gồm storeId.

7. Cần hỗ trợ?

Nếu bạn đã xác nhận mình bị ảnh hưởng nhưng gặp phải tình huống mà API hiện tại không bao phủ trong quá trình thích ứng, hoặc bạn vẫn còn thắc mắc về các tiêu chí quyết định, hãy gửi vé Open Platform hoặc liên hệ với quản lý tài khoản SHOPLINE của bạn để được trợ giúp.

Bài viết này được dịch bằng AI và có thể chứa những sai sót. Để có thông tin chính xác nhất, vui lòng tham khảo phiên bản tiếng Anh gốc.