開放 API

星課程表的開放 API 讓你的腳本、外掛或自動化工具能用 HTTP 請求讀取自己的課表、備忘錄和課堂筆記，也可以在獲得夥伴關係授權後查詢夥伴的固定課表並比對共同空堂時間。驗證基於「應用程式密碼」 —— 在「我的 → 開放 API」產生，可獨立刪除 / 旋轉，不影響登入密碼。

管理我的應用程式密碼查看端點

HTTP Basic Auth

使用者名稱 = 你的星 ID，密碼 = 在網頁 / App 產生的應用程式密碼。

可獨立撤銷

一個帳號最多 5 個，隨時旋轉 / 刪除，舊密碼立刻失效。

夥伴授權

只讀取已接受的夥伴關係，夥伴課表僅限對方目前固定的課表。

限速 60/分鐘

單一密碼每分鐘 60 次，超出回傳 429。

驗證

所有 /v1/open/* 介面都要求帶 HTTP Basic Auth:

Authorization: Basic base64("星ID:應用程式密碼")

`curl` 直接傳 `-u` 參數會自動完成 base64 編碼:

curl -u "你的星ID:你的應用程式密碼" \
  https://starschedule.xingqingchuang.com/api/v1/open/schedules

驗證失敗一律回傳 401 + { code: 401, message, data: null }，回應標頭帶 WWW-Authenticate: Basic。備忘錄、課堂筆記、夥伴課表和空堂時間介面使用同一個應用程式密碼即可存取，資料範圍始終限定在目前帳號自己的資料（夥伴資料僅限已接受的夥伴關係）。

權限

應用程式密碼預設帶 read 權限，涵蓋所有讀取介面。勾選寫入權限後可建立、修改、刪除備忘錄、待辦與筆記；只讀密碼寫入會被拒絕（403）。

read — 讀取你自己的課表、備忘錄、筆記、成績與校園資料。
write:daily — 另外可以建立、修改、刪除你的備忘錄、待辦與課堂筆記。

OpenAPI 描述檔

下面每個介面都由伺服器自己的函式註冊表產生 OpenAPI 3.1 描述，不會與實作脫節。可以直接把用戶端產生器指向它，也可以自己閱讀。

openapi.json

端點

GET/v1/open/schedules

列出目前帳號下所有未刪除的課表。

回應範例

{
  "code": 0,
  "message": "ok",
  "data": {
    "schedules": [
      { "uid": "abcd1234...", "name": "2025 春季" },
      { "uid": "efgh5678...", "name": "实习课表" }
    ]
  }
}

GET/v1/open/schedules/{uid}

讀取單張課表的詳細資料。

參數

include(query)— 以逗號分隔的子區段。可選 courses / adjustments / exams / clubs。不傳 = 全部。
uid(path)— 上一個介面回傳的 schedule uid。

回應範例

{
  "code": 0,
  "message": "ok",
  "data": {
    "schedule": {
      "uid": "abcd1234...",
      "name": "2025 春季",
      "term": {
        "uid": "term-...",
        "name": "2024-2025 第二学期",
        "startDate": "2025-02-24",
        "totalWeeks": 18
      },
      "courses": [ /* course_uid, name, color, credit, note ... */ ],
      "courseSessions": [ /* weekday, start/end section, start/end week, location, teacher ... */ ],
      "temporaryAdjustments": [ /* 停课 / 换时间 / 换地点 */ ],
      "exams": [ /* 考试日程 */ ],
      "clubActivities": [ /* 社团活动 */ ]
    },
    "meta": { "include": ["adjustments", "clubs", "courses", "exams"] }
  }
}

擴充端點

GET/v1/open/memos

讀取目前帳號的備忘錄（日常紀錄）。

參數

from / to(query)— 依日期篩選，格式為 YYYY-MM-DD。
updatedSince(query)— 只回傳此時間之後更新的紀錄，方便增量同步。
todo(query)— 可選 true / false，依待辦狀態篩選。

回應範例

{
  "code": 0,
  "message": "ok",
  "data": {
    "items": [
      {
        "uid": "memo-uid",
        "date": "2025-03-12",
        "content": "提交实验报告",
        "color": "#4F46E5",
        "isTodo": true,
        "completedAt": null,
        "deadlineAt": "2025-03-15T23:59:00+08:00",
        "reminderAt": null,
        "createdAt": "2025-03-01T08:00:00Z",
        "updatedAt": "2025-03-12T10:00:00Z"
      }
    ],
    "nextCursor": null
  }
}

GET/v1/open/class-notes

讀取目前帳號的課堂筆記，可依課表、課程、課次和上課日期篩選。

參數

scheduleUid / courseUid / sessionUid(query)— 可選的課表、課程和課次 UID。只能讀取目前帳號自己的資料。
occurrenceDate(query)— 依課堂發生日期篩選，格式為 YYYY-MM-DD。
include(query)— 可選 assets,topic。assets 回傳圖片資產中繼資料（uid / mimeType / sort）；圖片檔案下載暫不透過開放 API 提供。

回應範例

{
  "code": 0,
  "message": "ok",
  "data": {
    "items": [
      {
        "uid": "note-uid",
        "scheduleUid": "schedule-uid",
        "courseUid": "course-uid",
        "sessionUid": "session-uid",
        "occurrenceDate": "2025-03-12",
        "content": "老师强调了递归边界条件。",
        "topic": "算法基础",
        "createdAt": "2025-03-12T15:30:00Z",
        "updatedAt": "2025-03-12T15:40:00Z",
        "assets": []
      }
    ],
    "nextCursor": null
  }
}

GET/v1/open/buddies

列出目前帳號已建立的夥伴關係。只有已接受的夥伴關係會被回傳。

回應範例

{
  "code": 0,
  "message": "ok",
  "data": {
    "items": [
      {
        "linkId": "buddy-link-uid",
        "peer": {
          "sid": "ABC12345",
          "nickname": "小明",
          "school": "某某大学",
          "avatarUrl": null
        },
        "state": "accepted",
        "hasPinnedSchedule": true,
        "updatedAt": "2025-03-09T17:30:00Z"
      }
    ],
    "nextCursor": null
  }
}

GET/v1/open/buddies/{linkId}/schedule

回傳夥伴目前固定的課表。不能查詢夥伴的其他課表。

參數

linkId(path)— 夥伴清單回傳的關係 ID，關係必須屬於目前帳號且狀態為 accepted。

回應範例

{
  "code": 0,
  "message": "ok",
  "data": {
    "buddy": {
      "linkId": "buddy-link-uid",
      "sid": "ABC12345",
      "nickname": "小明"
    },
    "pinnedSchedule": {
      "uid": "schedule-uid",
      "name": "2025 春季",
      "term": {
        "name": "2024-2025 第二学期",
        "startDate": "2025-02-24",
        "totalWeeks": 18
      },
      "courses": [ /* 课程和上课节次 */ ],
      "temporaryAdjustments": [ /* 停课 / 换时间 / 换地点 */ ],
      "timeScheme": { "sections": [ /* 节次时间 */ ] }
    }
  }
}

POST/v1/open/free-time/compare

比對目前帳號與一個或多個夥伴固定課表的共同空堂時間。

參數

selfScheduleUid(body)— 目前帳號自己的課表 UID。
linkIds(body)— 夥伴關係 ID 清單。伺服器會自動讀取每位夥伴的固定課表，不能傳入夥伴 scheduleUid。
dateFrom / dateTo(body)— 日期範圍，最長 31 天。

回應範例

{
  "code": 0,
  "message": "ok",
  "data": {
    "basis": "section",
    "timezone": "Asia/Shanghai",
    "participantCount": 2,
    "slots": [
      {
        "date": "2025-03-10",
        "weekday": 1,
        "week": 3,
        "startSection": 3,
        "endSection": 4,
        "startTime": "10:10",
        "endTime": "11:50",
        "durationMinutes": 100
      }
    ],
    "warnings": []
  }
}

夥伴課表和空堂時間的安全界線

夥伴介面只允許存取已接受的關係。夥伴課表一律由伺服器從對方目前的固定課表解析，不能查詢對方其他課表。空堂時間介面只回傳所有參與者的共同空堂時段，不回傳誰在什麼時候有課、課程名稱、教師或地點。夥伴尚未設定固定課表時，不會使用其他課表代替，介面會略過該夥伴並在 warnings 中說明。

全部介面

身分：確認密碼有效，並查看它擁有的權限。

GET /v1/open/me

課表：目前週次檢視、依日期區間解析調休後的實際上課安排，以及每張課表的課程、學期、時間方案與考試。

GET /v1/open/schedules
GET /v1/open/schedules/{uid}
GET /v1/open/schedules/{uid}/courses
GET /v1/open/schedules/{uid}/time-scheme
GET /v1/open/schedules/{uid}/adjustments
GET /v1/open/schedules/{uid}/exams
GET /v1/open/schedules/{uid}/clubs
GET /v1/open/terms
GET /v1/open/timetable/current
GET /v1/open/timetable/occurrences
GET /v1/open/exams
GET /v1/open/club-activities

日程：備忘錄、待辦與課堂筆記，支援篩選與增量讀取。

GET /v1/open/memos
GET /v1/open/todos
GET /v1/open/class-notes

校園：你的成績、考勤與課程座位。

GET /v1/open/campus
GET /v1/open/campus/grades
GET /v1/open/campus/attendance
GET /v1/open/campus/seats

全量：分區變更摘要，以及一次取回整份同步快照。

GET /v1/open/snapshot/summary
GET /v1/open/snapshot

學習夥伴：已接受的夥伴關係、對方的固定課表，以及空閒時間比較。

GET /v1/open/buddies
GET /v1/open/buddies/{linkId}/schedule
POST /v1/open/free-time/compare

寫入（需要 write:daily）：建立、修改、刪除你的備忘錄、待辦與課堂筆記。

POST /v1/open/memos
PATCH /v1/open/memos/{uid}
DELETE /v1/open/memos/{uid}
POST /v1/open/todos
PATCH /v1/open/todos/{uid}
POST /v1/open/todos/{uid}/complete
DELETE /v1/open/todos/{uid}
POST /v1/open/class-notes
PATCH /v1/open/class-notes/{uid}
DELETE /v1/open/class-notes/{uid}

限速

每個應用程式密碼 60 次/分鐘，滑動視窗。超過限速回傳 429 + { code: 429, message, data: null }，回應標頭帶 RateLimit-* 系列（draft-7）欄位說明剩餘配額。

如果需要更高頻率（例如儀表板輪詢），建議在本機快取介面結果 + 用 Last-Modified 語意自行降頻，而不是反覆呼叫 API。

錯誤碼

HTTP	code	含義
401	401	未帶憑證 / 星 ID 或密碼錯誤 / 密碼已被撤銷
404	404	課表 uid 不存在或屬於其他帳號
403	403	沒有對應資料權限，或無權存取該夥伴關係
409	409	夥伴關係尚未接受（未建立聯繫）；夥伴未設定固定課表時不會報錯，而是回傳 pinnedSchedule: null 或在比對結果 warnings 中說明
429	429	單一密碼超過 60 次/分鐘
500	500	伺服器讀取課表失敗，請稍後再試