Appearance
🧪 Hướng Dẫn Test Nhanh & Mẫu Dữ Liệu
Trang tài liệu này cung cấp dữ liệu mẫu chuẩn (Mock Data) và các lệnh kiểm thử nhanh giúp bạn kiểm tra toàn diện luồng tích hợp API từ máy tính hoặc Terminal chỉ trong 1 phút.
1. Dữ Liệu Mẫu Chuẩn Dùng Cho Test
Dưới đây là các dữ liệu mẫu đã được kiểm nghiệm, bạn có thể sao chép và sử dụng ngay lập tức:
A. Chuỗi Ảnh Base64 Mẫu (Hợp lệ, nhẹ, dùng cho TikTok & Shopee)
Đây là chuỗi Base64 hợp lệ của một tệp ảnh JPEG mẫu siêu nhẹ (1x1 pixel trong suốt hoặc ảnh mẫu nhỏ), không chứa tiền tố data:image:
text
/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAP//////////////////////////////////////////////////////////////////////////////////////wgALCAABAAEBAREA/8QAFBABAAAAAAAAAAAAAAAAAAAAAP/aAAgBAQABPxA=B. Link Ảnh Public Mẫu (Dùng cho Shopee image_url)
text
https://images.unsplash.com/photo-1521572267360-ee0c2909d518?w=500&q=80C. Mã Ảnh Mẫu Trên CDN Shopee (Dùng cho Shopee image_key)
text
vn-11134207-7ras8-m427e1f48y0hbf2. Kịch Bản Test 5 Bước
Bước 1: Kiểm tra tình trạng hoạt động của Gateway (Không cần key)
Lệnh này xác nhận máy chủ Gateway và kết nối tới Shopee / TikTok đang sẵn sàng:
bash
curl -X GET "https://api.yourdomain.com/v1/health"Kết quả kỳ vọng: {"ok": true, "upstreams": {"shopee": true, "tiktok": true}}
Bước 2: Kiểm tra thông tin & quyền hạn của Key
Xác nhận xem Key của bạn có hợp lệ và được cấp quyền sàn nào:
bash
curl -X GET "https://api.yourdomain.com/v1/me" \
-H "X-API-Key: YOUR_API_KEY"Kết quả kỳ vọng: Nhận HTTP 200 OK, trường platforms chứa sàn bạn cần sử dụng (["shopee"] hoặc ["tiktok"]), status: "active".
Bước 3: Test tìm kiếm Shopee với ảnh mẫu URL
Thực hiện tìm kiếm với ảnh mẫu từ Unsplash và Cookie Shopee của bạn:
bash
curl -X POST "https://api.yourdomain.com/v1/shopee/search" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"cookie": "SPC_EC=your_cookie_here...",
"image_url": "https://images.unsplash.com/photo-1521572267360-ee0c2909d518?w=500&q=80",
"country": "VN",
"page": 1
}'Kết quả kỳ vọng: Nhận HTTP 200 OK chứa mảng data.items các sản phẩm áo thun tương đồng từ Shopee.
Bước 4: Test tìm kiếm TikTok Shop với ảnh Base64 mẫu
bash
curl -X POST "https://api.yourdomain.com/v1/tiktok/search" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"image_base64": "/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAP//////////////////////////////////////////////////////////////////////////////////////wgALCAABAAEBAREA/8QAFBABAAAAAAAAAAAAAAAAAAAAAP/aAAgBAQABPxA="
}'Kết quả kỳ vọng: Nhận HTTP 200 OK chứa mảng data.products từ TikTok Shop.
Bước 5: Test upload tệp ảnh lên TikTok CDN
Tạo một file ảnh nhỏ hoặc sử dụng ảnh có sẵn trên máy:
bash
curl -X POST "https://api.yourdomain.com/v1/tiktok/upload" \
-H "X-API-Key: YOUR_API_KEY" \
-F "file=@./sample.jpg"Kết quả kỳ vọng: Nhận HTTP 200 OK chứa trường data.url bắt đầu bằng https://p16-oec-va.ibyteimg.com/....
3. Bảng Kiểm Tra Kết Quả Test (Diagnostics Matrix)
| Mã phản hồi | Ý nghĩa kết quả | Hành động tiếp theo |
|---|---|---|
200 OK | Kết nối & nghiệp vụ thành công 100% | Bắt đầu ghép dữ liệu vào giao diện ứng dụng của bạn |
401 INVALID_KEY | Sai key hoặc key chưa kích hoạt | Kiểm tra lại chuỗi X-API-Key, liên hệ quản trị viên nếu cần |
403 PLATFORM_NOT_ALLOWED | Key chưa được cấp quyền cho sàn này | Liên hệ admin để mở quyền sàn tương ứng |
422 VALIDATION_ERROR | Payload JSON thiếu trường bắt buộc | Đối chiếu JSON gửi đi với tài liệu API Reference |
429 RATE_LIMITED | Gửi quá nhanh trong 1 phút | Đọc header Retry-After và hạ tần suất request |
429 QUOTA_EXCEEDED | Hết hạn mức tìm kiếm | Liên hệ quản trị viên để gia hạn thêm quota |
502 UPSTREAM_ERROR | Sàn upstream (Shopee/TikTok) bị timeout | Thử lại sau 1-2 phút hoặc kiểm tra cookie Shopee |