KalaKarma 會員排盤 API

以 kalakarma.app 的已驗證會員身分排盤、保存結果，並建立可撤銷的分享連結。

開啟 Chart Service →

認證

會員 API 使用既有 OIDC 短效 access token，以 Authorization: Bearer <token> 呼叫下列 API。一般排盤與分享請在 kalakarma.app 操作；chart.kalakarma.services 是收件者的觀看頁。Token 屬於你自己的會員身分，不可分享；分享星盤請使用回傳的分享網址。

API v1

GET    /api/v1/chart-service/catalog
POST   /api/v1/chart-service/casts
GET    /api/v1/chart-service/casts
GET    /api/v1/chart-service/casts/{id}
DELETE /api/v1/chart-service/casts/{id}
GET    /api/v1/chart-service/casts/{id}/shares
POST   /api/v1/chart-service/casts/{id}/shares
DELETE /api/v1/chart-service/casts/{id}/shares/{share_id}
DELETE /api/v1/chart-service/casts/{id}/share
GET    /api/v1/chart-service/shared/{token}  # only a published snapshot

計算範例

{
  "kind": "natal",
  "title": "我的本命星盤",
  "language": "zh",
  "subjects": [{
    "display_name": "Example",
    "birth_local_date": "1990-03-04",
    "birth_local_time": "08:00",
    "birth_time_known": true,
    "birth_tz_id": "Asia/Taipei",
    "birth_latitude": 25.033,
    "birth_longitude": 121.5654
  }],
  "options": {
    "natalHouseSystem": "wholesign",
    "mundaneHouseSystem": "placidus"
  }
}

可改用 subject_ids（你的名單 UUID 陣列），不能和 subjects 同時傳送。synastry / hehun 需要兩筆資料。時間重複的日光節約切換時段，須提供 birth_utc_offset_minutes。

盤種：natal、synastry、bazi、lunar、ziwei、vedic、qimen、tibetan、swarig、perpetual、hehun。

紫微 school：ZhongZhou / FeiXing / QinTian / SanHe / ZiYun；gender：Male / Female。奇門 qimen_mode：hour / ke；qimen_method：拆補 / 符頭，night_zi：次日 / 當日。查詢時間：target_year、target_date、target_time。

結果與分享

POST /casts 回傳 id、result.data（計算資料）、result.html（唯讀盤面）、warnings 與 engine。保存預設為私人。

POST /casts/{id}/shares 傳入 {} 預設全部資訊；或 {"label":"給老師", "sections":["wheel","planets","aspects"], "expires_days":30}。可用區塊列在 available_sections。本命盤回傳 chart.kalakarma.services/natal-chart/{token}，合盤回傳 chart.kalakarma.services/synastry/{token}。同一張盤可建立多個連結，各自保存不可修改的資訊選擇。網址只在建立時回傳，請複製保存。GET /casts/{id}/shares 列出連結；DELETE /casts/{id}/shares/{share_id} 僅停用指定連結。DELETE /casts/{id}/share 停用全部連結。刪除星盤也會停用全部連結。觀看頁無法用網址參數取得未分享的區塊。

計算約定

吠陀：Swiss Ephemeris Lahiri、Whole Sign、真交點、D1 / D9、Vimshottari（每年365.25日）。奇門：UTC+8 時家拆補或符頭；刻家採 Institute 十分鐘農曆加總法。藏曆 / SwaRig 沿用現有近似規則。每張盤保存當次結果，後續更動名單不會改寫。

每位會員最多保存1000張盤。計算忙碌會回429，可稍候重試。一般排盤約數秒；萬年曆較久，請允許130秒等待。輸入錯誤422、權限不足403、找不到或撤銷404。