Lấy Danh Sách Popup Banner
API lấy danh sách popup banner của shop với platform là mini_app. Popup banner sẽ hiển thị khi người dùng mở app, có thể có nút đóng và sẽ xuất hiện lại khi người dùng reload app. API hỗ trợ loại trừ các banner đã hiển thị trước đó.
GET https://api.socdo.vn/mini-app/v1/get-popup-banner
Request Headers
Token-Seller: YOUR_TOKEN_SELLER
Shop-ID: 8185

Hoặc:

Authorization: Bearer YOUR_TOKEN_SELLER
Shop-ID: 8185
Query Parameters
GET /get-popup-banner?shop_id=8185&exclude_id=22,23
Tham số
Tham số Loại Bắt buộc Mô tả
Token-Seller header Token-Seller từ API get-token-seller (hoặc Authorization: Bearer)
Shop-Id header/query ID của shop cần lấy popup banner
exclude_id query - ID hoặc danh sách ID (comma-separated) của các banner đã hiển thị để loại trừ (ví dụ: 22 hoặc 22,23)
Response thành công (200)
{
    "success": true,
    "message": "Lấy danh sách popup banner thành công",
    "shop_id": 8185,
    "data": [
        {
            "id": 22,
            "title": "Test Flash Sale 13213",
            "image_url": "https://socdo.cdn.vccloud.vn/uploads/popup-banners/8185/mini-app-1763697986-6675.jpg",
            "target_url": "Test Flash Sale 12323",
            "start_at": "2025-11-20 10:49:00",
            "end_at": "2025-11-30 10:49:00",
            "is_active": true,
            "priority": 1,
            "display_limit_per_user": 1,
            "click_count": 0,
            "shop_id": 8185,
            "platform": "mini_app",
            "created_at": "2025-11-21 03:49:40",
            "updated_at": "2025-11-21 04:06:26"
        }
    ],
    "total": 1
}
Response lỗi (401 - Thiếu Token-Seller)
{
    "success": false,
    "message": "Thiếu Token-Seller header"
}
Response lỗi (400 - Shop-Id không hợp lệ)
{
    "success": false,
    "message": "Shop-Id không hợp lệ. Cần Shop-Id header hoặc shop_id parameter"
}
Response lỗi (401 - Token-Seller không hợp lệ)
{
    "success": false,
    "message": "Token-Seller không hợp lệ hoặc đã hết hạn",
    "error": "Token expired"
}
Response lỗi (401 - Shop-Id không khớp)
{
    "success": false,
    "message": "Shop-Id không khớp với Token-Seller"
}
Response lỗi (500 - Lỗi database)
{
    "success": false,
    "message": "Lỗi truy vấn database: ..."
}
Ví dụ JavaScript
// Lấy danh sách popup banner
async function getPopupBanners(shopId, excludeIds = []) {
    try {
        const params = new URLSearchParams({
            shop_id: shopId
        });
        
        // Thêm exclude_id nếu có
        if (excludeIds.length > 0) {
            params.append('exclude_id', excludeIds.join(','));
        }
        
        const response = await fetch(`https://api.socdo.vn/mini-app/v1/get-popup-banner?${params}`, {
            method: 'GET',
            headers: {
                'Token-Seller': localStorage.getItem('seller_token'),
                'Shop-ID': shopId.toString()
            }
        });
        
        const result = await response.json();
        
        if (result.success) {
            console.log('Danh sách popup banner:', result.data);
            console.log('Tổng số:', result.total);
            return result;
        } else {
            console.error('Lỗi lấy popup banner:', result.message);
            return result;
        }
    } catch (error) {
        console.error('Lỗi kết nối:', error);
        return { success: false, message: 'Lỗi kết nối mạng' };
    }
}

// Sử dụng - Lấy tất cả popup banner
getPopupBanners(8185).then(result => {
    if (result.success && result.data.length > 0) {
        // Hiển thị popup banner đầu tiên
        const firstBanner = result.data[0];
        showPopupBanner(firstBanner);
    }
});

// Sử dụng - Loại trừ các banner đã hiển thị
const displayedBannerIds = [22, 23]; // Các banner đã hiển thị
getPopupBanners(8185, displayedBannerIds).then(result => {
    if (result.success && result.data.length > 0) {
        // Hiển thị popup banner tiếp theo (không phải 22, 23)
        const nextBanner = result.data[0];
        showPopupBanner(nextBanner);
    }
});

// Hàm hiển thị popup banner
function showPopupBanner(banner) {
    // Tạo modal/popup để hiển thị banner
    const modal = document.createElement('div');
    modal.className = 'popup-banner-modal';
    modal.innerHTML = `
        
    `;
    document.body.appendChild(modal);
}
Ví dụ cURL
curl -X GET "https://api.socdo.vn/mini-app/v1/get-popup-banner?shop_id=8185" \
  -H "Token-Seller: YOUR_TOKEN_SELLER" \
  -H "Shop-ID: 8185"

# Với exclude_id
curl -X GET "https://api.socdo.vn/mini-app/v1/get-popup-banner?shop_id=8185&exclude_id=22,23" \
  -H "Token-Seller: YOUR_TOKEN_SELLER" \
  -H "Shop-ID: 8185"
Lưu ý quan trọng
  • Token-Seller Required: API yêu cầu Token-Seller hợp lệ từ API get-token-seller (có thể gửi qua header Token-Seller hoặc Authorization: Bearer)
  • Shop Validation: Token-Seller và Shop-Id phải khớp với nhau
  • Platform Filter: API chỉ trả về popup banner có platform = 'mini_app'
  • Active Status: Chỉ lấy popup banner có is_active = 1
  • Time Range: Chỉ lấy popup banner trong khoảng thời gian hiệu lực (start_at <= now <= end_at)
  • Priority Sorting: Popup banner được sắp xếp theo priority DESC (ưu tiên cao hơn hiển thị trước)
  • Exclude IDs: Có thể loại trừ các banner đã hiển thị bằng tham số exclude_id (hỗ trợ nhiều ID, cách nhau bằng dấu phẩy)
  • Image URL: Tự động format image_url với CDN nếu là relative path
  • Display Limit: Trường display_limit_per_user cho biết số lần hiển thị tối đa cho mỗi user (0 = không giới hạn)
  • Click Count: Trường click_count theo dõi số lần người dùng click vào popup banner
Luồng xử lý
  1. Kiểm tra Token-Seller từ header Token-Seller hoặc Authorization
  2. Lấy Shop-Id từ header Shop-Id hoặc query parameter shop_id
  3. Validate Token-Seller và Shop-Id bằng JWT
  4. Kiểm tra shop_id trong token có khớp với Shop-Id header không
  5. Xây dựng query với điều kiện: shop_id, platform='mini_app', is_active=1, và thời gian hiệu lực
  6. Loại trừ các banner trong exclude_id nếu có
  7. Sắp xếp theo priority DESC, id DESC
  8. Xử lý URL hình ảnh với CDN nếu cần
  9. Trả về danh sách popup banner với cấu trúc JSON chuẩn
Giải thích Response Fields
Trường Loại Mô tả
id number ID của popup banner
title string Tiêu đề popup banner
image_url string URL đầy đủ của hình ảnh popup banner (đã được format với CDN nếu cần)
target_url string|null URL khi click vào popup (null nếu không có)
start_at string|null Thời gian bắt đầu hiển thị (format: YYYY-MM-DD HH:mm:ss, null nếu không có)
end_at string|null Thời gian kết thúc hiển thị (format: YYYY-MM-DD HH:mm:ss, null nếu không có)
is_active boolean Trạng thái: true = bật, false = tắt
priority number Độ ưu tiên (số cao hơn = ưu tiên hơn, sắp xếp theo DESC)
display_limit_per_user number Số lần hiển thị tối đa cho mỗi user (0 = không giới hạn)
click_count number Số lần click vào popup banner
shop_id number ID của shop sở hữu popup banner
platform string Platform của popup banner (luôn là 'mini_app' trong API này)
created_at string Thời gian tạo (format: YYYY-MM-DD HH:mm:ss)
updated_at string Thời gian cập nhật (format: YYYY-MM-DD HH:mm:ss)
API Liên Quan