Chuyển tới nội dung chính

🎥 YouTube Integration API

Tài liệu này hướng dẫn cách sử dụng các API kết nối kênh YouTube của Admin và lấy danh sách bài học/video cho học viên.

🔐 1. Admin OAuth 2.0 Flow​

Dành cho Quản trị viên kết nối kênh YouTube chính thức của hệ thống.

GET /api/admin/youtube/auth​

Yêu cầu người dùng Admin xác thực ứng dụng Google để lấy refresh_token dài hạn.

  • Headers:
    • X-Admin-Key: Khóa bí mật của Admin (khớp với cấu hình ADMIN_API_KEY ở Worker).
  • Response:
    • 302 Redirect sang Google Consent Screen.

GET /api/admin/youtube/callback​

Hứng callback từ Google OAuth 2.0, thực hiện đổi code lấy refresh_token và lưu bảo mật vào cơ sở dữ liệu InsForge.

  • Query Parameters:
    • code: Mã xác thực của Google.
    • state: Admin key để tránh CSRF.
  • Response:
    • HTML hiển thị thông báo kết nối thành công hoặc mã lỗi.

GET /api/admin/youtube/status​

Kiểm tra trạng thái kết nối tài khoản YouTube của Admin.

  • Headers:
    • X-Admin-Key: Khóa bí mật của Admin.
  • Response:
    • 200 OK
    {
      "connected": true,
      "data": {
        "channel_id": "UCxxxxxx",
        "expires_at": "2026-06-13T21:30:00Z",
        "scope": "https://www.googleapis.com/auth/youtube.readonly",
        "updated_at": "2026-06-13T20:30:00Z"
      }
    }

🎓 2. API Học Viên (Playlists & Videos)​

Tất cả các API này yêu cầu học viên đăng nhập bằng Google Sign-In và đính kèm JWT Token vào Header.

POST /api/auth/register​

Tự động đăng ký và đồng bộ thông tin học viên vào bảng customers khi đăng nhập lần đầu thông qua InsForge Google OAuth.

  • Headers:
    • Authorization: Bearer <STUDENT_JWT_TOKEN>
  • Response:
    • 201 Created / 200 OK
    {
      "success": true,
      "customerId": "uuid-cua-hoc-vien"
    }

GET /api/playlists​

Lấy danh sách các playlists (danh sách phát/khóa học) từ kênh YouTube của Admin.

  • Headers:
    • Authorization: Bearer <STUDENT_JWT_TOKEN>
  • Response:
    • 200 OK
    {
      "success": true,
      "data": [
        {
          "id": "PLxxxxx",
          "title": "Học Chứng Khoán Cơ Bản",
          "description": "Các bài học từ A-Z dành cho người mới bắt đầu.",
          "thumbnail": "https://i.ytimg.com/vi/xxxx/mqdefault.jpg",
          "videoCount": 15,
          "publishedAt": "2026-05-20T10:00:00Z",
          "youtubeUrl": "https://www.youtube.com/playlist?list=PLxxxxx"
        }
      ]
    }

GET /api/playlists/:playlistId/videos​

Lấy danh sách các videos trong một playlist cụ thể.

  • Headers:
    • Authorization: Bearer <STUDENT_JWT_TOKEN>
  • Response:
    • 200 OK
    {
      "success": true,
      "data": [
        {
          "id": "dQw4w9WgXcQ",
          "title": "Bài 1: Tổng quan về Thị trường Chứng khoán Việt Nam",
          "description": "Hướng dẫn các khái niệm cơ bản đầu tiên.",
          "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/mqdefault.jpg",
          "position": 0,
          "youtubeUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
        }
      ]
    }