開發者文件｜teacher.place

01 / START

一個 GET，就能開始。

填入教學站台網址與課程 ID，即可複製範例開始串接。

API 根網址課程 ID

課程 ID 位於後台課程編輯網址中：/adminV2/course/課程ID/basic。

const response = await fetch("https://school.example.com/api/v1/courses/COURSE_ID", {
  credentials: 'omit'
});
const { data, error } = await response.json();
if (!response.ok) throw new Error(error.message);
console.log(data.name, data.price);

每次載入取得最新資料。學生登入、購課與付費教材，透過原站台頁面完成。

02 / ENDPOINTS

目前提供的公開資料

點開接口，查看路徑參數、回應欄位與範例。

GET取得已上架課程/courses/{courseId}

取得已上架課程

路徑參數	用途
`courseId`	課程 ID

{
  "data": {
    "id": "COURSE_ID",
    "name": "水彩入門",
    "description": "從基礎筆法開始學習水彩。",
    "introductionHtml": "<p>課程介紹</p>",
    "coverUrl": "https://images.example/course.jpg",
    "hero": {
      "type": "image",
      "imageUrls": [],
      "videoUrl": ""
    },
    "price": 1200,
    "currency": "TWD",
    "paymentType": "one_time",
    "learningPoints": [
      "掌握基礎筆法"
    ],
    "includedItems": [
      "線上教材"
    ],
    "links": {
      "course": "https://school.example.com/courses/watercolor",
      "login": "https://school.example.com/courses/watercolor?auth=login",
      "register": "https://school.example.com/courses/watercolor?auth=register",
      "checkout": "https://school.example.com/checkout?courseId=COURSE_ID",
      "learning": "https://school.example.com/course/watercolor/"
    }
  }
}

查看回應欄位

欄位	格式	說明
`id`	string	課程永久 ID。
`name`	string	課程名稱。
`description`	string	課程摘要。
`introductionHtml`	string	課程介紹 HTML，呈現前請清理內容。
`coverUrl`	string	課程封面網址。
`hero`	object	主視覺類型、圖片與介紹影片網址。
`price`	integer	TWD 整數售價，0 表示免費。
`currency`	string	幣別，固定為 TWD。
`paymentType`	string	one_time 為單次付費；subscription 為訂閱。
`learningPoints`	array	課程學習重點。
`includedItems`	array	課程包含項目。
`links`	object	原站台的頁面連結，供使用者點擊開啟。訂閱型課程的 checkout 指向原課程方案頁。

GET取得一頁式課程資料/courses/{courseId}/page-data

一次取得站台、課程、章節與操作連結。此格式與平台 Liquid 銷售頁共用，適合自訂到達頁。

路徑參數	用途
`courseId`	課程 ID

{
  "data": {
    "schemaVersion": "course-page.v1",
    "site": {
      "id": "site_demo",
      "name": "示範教學網站",
      "logoUrl": ""
    },
    "course": {
      "id": "COURSE_ID",
      "name": "水彩入門",
      "price": 1200,
      "priceText": "NT$ 1,200",
      "isFree": false,
      "chapterCount": 1,
      "unitCount": 2
    },
    "chapters": [
      {
        "id": "CHAPTER_ID",
        "index": 1,
        "name": "第一章",
        "units": [
          {
            "id": "UNIT_ID",
            "index": 1,
            "name": "工具介紹",
            "preview": true
          }
        ]
      }
    ],
    "links": {
      "course": "https://school.example.com/courses/watercolor",
      "login": "https://school.example.com/courses/watercolor?auth=login",
      "register": "https://school.example.com/courses/watercolor?auth=register",
      "checkout": "https://school.example.com/checkout?courseId=COURSE_ID",
      "learning": "https://school.example.com/course/watercolor/"
    }
  }
}

查看回應欄位

欄位	格式	說明
`schemaVersion`	string	資料格式版本。
`site`	object	公開站台名稱與 Logo。
`course`	object	課程內容，並補上 priceText、isFree、chapterCount、unitCount。
`chapters`	array	已發布章節與單元。
`links`	object	課程、登入、註冊、結帳與開始上課連結。

GET取得已發布章節與單元/courses/{courseId}/chapters

按後台順序回傳；preview=true 的單元可直接試閱。此接口不回傳付費影片來源。

路徑參數	用途
`courseId`	課程 ID

{
  "data": [
    {
      "id": "CHAPTER_ID",
      "name": "第一章・認識水彩",
      "units": [
        {
          "id": "UNIT_ID",
          "name": "工具介紹",
          "preview": true
        },
        {
          "id": "PAID_UNIT_ID",
          "name": "進階技法",
          "preview": false
        }
      ]
    }
  ]
}

查看回應欄位

欄位	格式	說明
`id`	string	—
`name`	string	—
`units`	array	—

GET取得公開試閱教材/courses/{courseId}/units/{chapterId}/{unitId}

僅限已發布且 preview=true 的單元。非試閱單元回 403，不接受學生 Token 解鎖。Mux 簽章約一小時，過期需重新取得。

路徑參數	用途
`courseId`	課程 ID
`chapterId`	章節 ID，取自章節接口
`unitId`	單元 ID，取自章節接口

{
  "data": {
    "id": "UNIT_ID",
    "chapterId": "CHAPTER_ID",
    "name": "工具介紹",
    "contentHtml": "<p>今天一起認識水彩工具。</p>",
    "video": {
      "provider": "url",
      "url": "https://video.example/lesson.mp4"
    }
  }
}

查看回應欄位

欄位	格式	說明
`id`	string	—
`chapterId`	string	—
`name`	string	—
`contentHtml`	string	—
`video`	object / null	—

只回傳已上架課程及已發布章節。preview=false 的單元只列出名稱，讀取教材會回 403。

03 / CONNECT

按鈕接上原站台流程

課程回應的 links 已包含完整網址，放進連結即可。

links.login學生登入

開啟原站台登入介面。

links.register學生註冊

開啟原站台註冊介面。

links.checkout立即購課

開啟原站台結帳或方案頁。

links.learning開始學習

由原站台驗證學生與購課權限。

// course 是課程接口回傳的 data
const button = document.querySelector('#buy');
button.href = course.links.checkout;
button.target = '_blank';
button.rel = 'noopener noreferrer';

結帳頁先將課程加入購物車，學生確認後才建立訂單；訂閱課程回原站台選方案。此 API 不處理帳密、訂單或付款，也不回傳學生的購課狀態。

04 / REFERENCE

回應格式與錯誤

成功讀取 data；失敗依 HTTP 狀態與 error.message 顯示提示。

400識別碼格式有誤。

403單元未開放試閱。

404站台或內容不存在／尚未發布。

405此 API 不支援寫入請求。

409課程售價設定有誤。

429依 Retry-After 秒數稍後重試。

500 / 503服務或影片設定暫時無法使用。

跨網站請求不帶登入 Cookie，不需自訂 header。支援 GET、HEAD 與 OPTIONS；其他方法回 405。

下載工程師／AI 串接指南 ↗下載 OpenAPI 3.0 規格 ↗