Lỗi "liên kết không hợp lệ" trong API: kiểm tra URL trước khi tạo đơn hàng

Lỗi "liên kết không hợp lệ" trong API có nghĩa là gì

Lỗi "liên kết không hợp lệ" có nghĩa là API không thể chấp nhận URL trong trường đối tượng của đơn hàng. Đây không phải lúc nào cũng là lỗi gõ sai địa chỉ. Dịch vụ có thể từ chối liên kết do định dạng không phù hợp, loại trang, chuyển hướng, hạn chế truy cập, mã hóa hoặc nền tảng không khớp với dịch vụ.

Quá trình kiểm tra thường diễn ra trước khi tạo đơn hàng. API nhận URL, xác định tên miền và đường dẫn, cố gắng nhận diện đối tượng: kênh, video, buổi phát trực tiếp, bài đăng hoặc hồ sơ. Nếu một trong các bước không vượt qua, đơn hàng sẽ không được tạo. Bản thân văn bản lỗi chung không cho thấy nguyên nhân — cần xem URL, tham số dịch vụ và toàn bộ phản hồi API.

Đối chiếu văn bản lỗi với phản hồi API

Cách diễn đạt và cấu trúc phản hồi khác nhau giữa các API. Đôi khi dịch vụ chỉ trả về thông báo, đôi khi thêm mã, tên trường hoặc mã định danh yêu cầu. Phản hồi đầy đủ hữu ích hơn trạng thái HTTP: ngay cả khi yêu cầu được gửi thành công, API vẫn có thể từ chối chính đơn hàng ở mức kiểm tra nghiệp vụ.

Ví dụ, một phản hồi điển hình có thể trông như sau: {"error":"invalid_link","message":"Invalid target URL","field":"link"}. Ở đây cần kiểm tra chính giá trị của trường link. Biến thể {"error":"target_not_supported"} thường chỉ ra không phải địa chỉ bị hỏng mà là loại đối tượng không được hỗ trợ. Tên trường và mã phụ thuộc vào tài liệu cụ thể.

Hãy lưu trạng thái phản hồi, nội dung phản hồi, mã định danh dịch vụ và request_id nếu API trả về. Không thêm token truy cập, cookie, chữ ký yêu cầu và tham số riêng tư của liên kết vào ticket.

Kiểm tra định dạng URL và giá trị trường trong yêu cầu

Một liên kết hoạt động trên trình duyệt có thể không vượt qua kiểm tra tự động. Đôi khi trường chỉ chứa mã định danh video, tên người dùng không có tên miền, văn bản từ tin nhắn hoặc địa chỉ rút gọn. Lỗi cũng xảy ra khi URL được truyền không phải dạng chuỗi mà là đối tượng lồng nhau hoặc mảng.

• Truyền URL công khai đầy đủ kèm giao thức https://.
• Kiểm tra tên miền: phải thuộc nền tảng của dịch vụ đã chọn.
• Xóa khoảng trắng ở đầu và cuối, ký tự xuống dòng, emoji và văn bản sau liên kết.
• Đối chiếu tên trường với tài liệu API: link, url, target hoặc tên khác.
• Đảm bảo yêu cầu truyền giá trị dạng chuỗi, không phải đối tượng chứa URL bên trong.

Dán địa chỉ thủ công thì tiện, nhưng có nhược điểm: rất dễ lọt ký tự vô hình hoặc đoạn mô tả bài đăng vào chuỗi. Trước khi gửi, hãy làm sạch giá trị nhưng không thay đổi chính đường dẫn và tham số nếu không cần thiết.

Mở rộng liên kết rút gọn và loại bỏ chuyển hướng thừa

Địa chỉ rút gọn và liên kết từ nút "Chia sẻ" thường đi qua một hoặc nhiều lần chuyển hướng. Trình duyệt tự động mở chúng, nhưng API của dịch vụ quảng bá có thể không đi theo chuyển hướng, chặn chúng hoặc nhận được trang trung gian yêu cầu đăng nhập.

Đối với đơn hàng, tốt hơn nên dùng địa chỉ chuẩn tắc: địa chỉ hiển thị trên thanh địa chỉ sau khi trang cần thiết tải xong hoàn toàn. Nhãn chiến dịch và tham số thời gian xem không phải lúc nào cũng gây trở ngại, nhưng tham số có thể dẫn đến cách hiển thị trang khác hoặc ảnh hưởng đến việc nhận diện đối tượng.

URL chuẩn tắc có nhược điểm: đôi khi phải lấy riêng, đặc biệt sau khi sao chép liên kết từ ứng dụng di động. Nhưng địa chỉ như vậy dễ kiểm tra thủ công hơn và dễ đối chiếu với quy tắc dịch vụ.

Chọn liên kết đến đối tượng mà dịch vụ chấp nhận

Dịch vụ có thể chỉ chấp nhận một loại đối tượng. Đơn hàng cho kênh sẽ không nhận liên kết đến bản ghi buổi phát trực tiếp, và dịch vụ cho lượt xem video sẽ không nhận hồ sơ tác giả. Bề ngoài cả hai URL đều hợp lệ, nhưng API đối chiếu cấu trúc địa chỉ với mục đích dịch vụ và từ chối đối tượng không phù hợp.

Kiểm tra danh mục dịch vụ: nền tảng, danh mục, target_type được phép và các hạn chế. Nếu API yêu cầu tham số riêng cho loại đối tượng, nó phải khớp với URL. Không thay địa chỉ nội dung bằng liên kết đến tìm kiếm, hashtag, bộ sưu tập, trang chủ hoặc trang cá nhân của tác giả.

• Để quảng bá kênh, truyền trang kênh.
• Để tăng lượt xem, dùng liên kết đến video hoặc bài đăng cụ thể.
• Đối với buổi phát trực tiếp đang hoạt động, truyền URL buổi phát nếu dịch vụ hỗ trợ định dạng live.
• Đối với cảm xúc và các hành động khác với bài đăng, dùng liên kết trực tiếp đến bài đăng.

Kiểm tra quyền riêng tư, bộ lọc độ tuổi và yêu cầu đăng nhập

API không chỉ kiểm tra hình thức URL mà còn cả khả năng truy cập của đối tượng. Nội dung có thể mở được với chủ kênh vì trình duyệt của họ đã đăng nhập, nhưng lại không truy cập được với máy chủ kiểm tra bên ngoài. Trong trường hợp này, dịch vụ thường trả về lỗi chung về liên kết không hợp lệ.

• Kiểm tra xem hồ sơ, kênh, bài đăng hoặc chính buổi phát trực tiếp có bị đóng không.
• Đảm bảo video không bị xóa, không bị chuyển sang bản nháp và không bị thay bằng bài đăng khác.
• Kiểm tra giới hạn độ tuổi: có thể yêu cầu xác nhận tuổi hoặc đăng nhập tài khoản.
• Tắt chế độ chỉ dành cho người đăng ký, thành viên hoặc người xem được duyệt nếu đang bật.
• Đảm bảo trang không hiển thị biểu mẫu đăng nhập, cảnh báo nội dung hoặc trang tạm kỹ thuật.

Mở liên kết trong cửa sổ riêng tư không đăng nhập. Nếu thay vì trang đích lại thấy yêu cầu đăng nhập, hãy thay đổi cài đặt truy cập hoặc chọn dịch vụ cho phép loại đối tượng đó, nếu có. Nhược điểm của kiểm tra trong cửa sổ riêng tư là không phải lúc nào cũng phát hiện được hạn chế khu vực và mạng.

Lưu ý đến địa chỉ khu vực, di động và nhúng

Một đối tượng có thể có URL máy tính, di động, bản địa hóa và nhúng. Địa chỉ từ ứng dụng hoặc webview đôi khi chứa các đoạn kỹ thuật mà API không nhận diện được. Trang bản địa hóa cũng có thể mở khác đi với máy chủ kiểm tra.

Mở liên kết đã sao chép trong trình duyệt thông thường và chờ tải xong hoàn toàn. Đối với yêu cầu, dùng địa chỉ web công khai từ thanh địa chỉ. Nếu nội dung bị hạn chế theo khu vực, hãy gỡ hạn chế nếu cài đặt nền tảng cho phép, hoặc không gửi đối tượng đó vào dịch vụ cần truy cập công khai.

Liên kết web công khai không cần đăng nhập và không có màn hình trung gian là lựa chọn đáng tin cậy nhất để kiểm tra API.

Loại trừ việc URL bị hỏng khi gửi yêu cầu

Liên kết có thể đúng trước khi gửi nhưng bị thay đổi khi tuần tự hóa JSON, lắp ghép tham số query, gửi form-data hoặc mã hóa lại. Các ký tự &, ?, # và % đặc biệt nhạy cảm. Ví dụ, dấu ampersand trong URL có thể trở thành dấu phân cách tham số của chính yêu cầu nếu địa chỉ được truyền mà không mã hóa đúng cách.

• So sánh URL gốc với giá trị trong yêu cầu HTTP thực tế.
• Kiểm tra nội dung yêu cầu trong log của client, proxy hoặc công cụ dành cho nhà phát triển.
• Đối với JSON, dùng tuần tự hóa chuẩn thay vì lắp ghép chuỗi thủ công.
• Không mã hóa URL hai lần nếu thư viện đã tự động làm việc đó.
• Kiểm tra cách xử lý ký tự Cyrillic trong đường dẫn và tham số địa chỉ.

Log giúp nhanh chóng tìm ra sự khác biệt, nhưng có nhược điểm: chúng có thể chứa khóa API, token và dữ liệu cá nhân. Hãy che các giá trị nhạy cảm trước khi ghi và truyền log.

Đối chiếu nền tảng, mã định danh dịch vụ và tham số đơn hàng

Một số API kiểm tra dịch vụ trước, sau đó mới đến tên miền và loại liên kết. URL của nền tảng khác, service_id lỗi thời hoặc target_type sai có thể dẫn đến cùng lỗi "liên kết không hợp lệ". Trong trường hợp này, thay đổi chính địa chỉ là vô ích cho đến khi sửa tham số đơn hàng.

Cập nhật danh mục dịch vụ qua phương thức API nếu có. Bộ nhớ đệm với danh sách cũ có thể lưu dịch vụ đã tắt hoặc yêu cầu trước đây của nó. Cập nhật danh mục thường xuyên có nhược điểm: làm tăng số lượng yêu cầu và có thể gặp giới hạn tần suất. Dùng bộ nhớ đệm có thời hạn lưu trữ giới hạn và cập nhật sau lỗi xác thực.

Kiểm tra liên kết theo thứ tự trước khi gửi lại

1. Sao chép URL đầy đủ không có văn bản, khoảng trắng và ký tự ẩn.
2. Mở nó trong cửa sổ riêng tư không đăng nhập tài khoản.
3. Kiểm tra rằng trang không bị đóng, không bị xóa và không yêu cầu đăng nhập.
4. Đảm bảo không có hạn chế độ tuổi, đăng ký hoặc khu vực.
5. Mở rộng liên kết rút gọn đến địa chỉ công khai cuối cùng.
6. Đối chiếu đối tượng trong URL với dịch vụ: kênh, video, buổi phát trực tiếp hoặc bài đăng.
7. Đối chiếu nền tảng, service_id và target_type với danh mục dịch vụ hiện hành.
8. Kiểm tra nội dung thực tế của yêu cầu HTTP và mã hóa URL.
9. Lưu toàn bộ phản hồi API và mã định danh yêu cầu không có token và dữ liệu riêng tư.

Nếu sau các bước kiểm tra này lỗi vẫn còn, hãy gửi cho bộ phận hỗ trợ liên kết ở dạng đã làm sạch, mã định danh dịch vụ, thời gian yêu cầu, trạng thái HTTP và toàn bộ văn bản phản hồi API. Điều này giúp phân biệt vấn đề URL với hạn chế của dịch vụ cụ thể hoặc sự cố kiểm tra phía dịch vụ.