能力索引
能力(capability)是這條 API 的授權單位。scope 命名空間是 lightup.<capability>,目錄是版本化的靜態清單。
目錄新增能力不會自動擴權。 租戶安裝應用時核准的是當下目錄的具體 id 集合,不是「全部」這個意圖;之後目錄多出來的能力要重新核准才會生效。
| 能力 | 資源型別 | 最低方案 | 可用狀態 | 說明 |
|---|---|---|---|---|
lightup.profile.self.read |
self | L1 | 正式 ga |
讀這張 token 代表的 service account |
lightup.person.read |
person | L2 | 正式 ga |
讀獲授權人員的最少欄位 |
lightup.person.metadata.read |
person | L2 | 正式 ga |
讀本 app 自己的人員 metadata |
lightup.person.metadata.write |
person | L2 | 正式 ga |
寫/刪本 app 自己的人員 metadata |
lightup.tenant.info.read |
tenant | L1 | 正式 ga |
讀租戶公開識別欄位 |
lightup.order.create |
tenant | L2 | 預覽 preview |
以目錄價格為租戶的客戶建立未付款訂單(僅機器流程) |
lightup.order.read |
tenant | L2 | 預覽 preview |
讀取本 app 建立的訂單狀態、金額與付款狀態(僅機器流程) |
lightup.order.cancel |
tenant | L2 | 預覽 preview |
取消本 app 建立的未付款訂單(僅機器流程) |
lightup.tag.read |
tenant | L2 | 預覽 preview |
讀租戶的客戶帶著哪些標籤、帶著某標籤的客戶,並以名稱查標籤與標籤分類(僅機器流程) |
lightup.person.resolve |
tenant | L2 | 預覽 preview |
把租戶的舊客戶 id 對應到 person id(僅機器流程) |
lightup.line.target |
tenant | L2 | 預覽 preview |
讀租戶的客戶能不能用 LINE 聯絡;能的話,回傳他在該租戶自己的 LINE 官方帳號下的 LINE user id(僅機器流程) |
lightup.tag.write |
tenant | L2 | 預覽 preview |
為客戶加上、移除租戶的標籤(僅機器流程) |
lightup.tag.define |
tenant | L2 | 預覽 preview |
在租戶既有的標籤分類下建立標籤(僅機器流程) |
lightup.line.message_group.read |
tenant | L2 | 預覽 preview |
以 id 或完整名稱讀取租戶的 LINE 訊息組:每則訊息的文字與媒體 id(僅機器流程) |
lightup.person.profile.read |
tenant | L2 | 預覽 preview |
以 id 讀取租戶指名客戶的名字、姓氏、顯示名稱、生日與性別(僅機器流程) |
lightup.person.wards.read |
tenant | L2 | 預覽 preview |
列出租戶的某位客戶目前監護中的孩子,附每個孩子的基本資料(僅機器流程) |
lightup.person.contact.read |
tenant | L2 | 規劃 planned |
以 id 讀取租戶指名客戶已驗證的登入手機與 email,以及各自的驗證時間 |
lightup.person.search |
tenant | L2 | 規劃 planned |
以完整的 email 或手機號碼精確查詢租戶的客戶,只回 person id |
lightup.person.list |
tenant | L2 | 規劃 planned |
依更新時間分頁列出租戶的客戶(只回 person id 與更新時間) |
lightup.person.write |
tenant | L2 | 規劃 planned |
建立沒有登入識別的客戶,並修改名字、姓氏、顯示名稱、生日與性別 |
lightup.person.wards.write |
tenant | L2 | 規劃 planned |
建立、修改與解除租戶的監護關係 |
lightup.person.marketing_consent.read |
tenant | L2 | 規劃 planned |
以 id 讀取租戶指名客戶的行銷同意狀態 |
lightup.person.marketing_consent.write |
tenant | L2 | 規劃 planned |
記錄或撤回客戶的行銷同意(必須帶同意時間與來源管道) |
lightup.audience.read |
tenant | L2 | 規劃 planned |
讀取租戶的分眾群組與成員 |
lightup.audience.write |
tenant | L2 | 規劃 planned |
建立與修改租戶的分眾群組與成員 |
lightup.membership.read |
tenant | L2 | 規劃 planned |
讀取租戶的會員方案與客戶的會員資格 |
lightup.membership.write |
tenant | L2 | 規劃 planned |
授予、修改與終止客戶的會員資格 |
lightup.loyalty.read |
tenant | L2 | 規劃 planned |
讀取租戶的會員等級、客戶點數餘額與紀錄 |
lightup.loyalty.points.write |
tenant | L2 | 規劃 planned |
發放與扣除客戶的點數 |
lightup.loyalty.tier.write |
tenant | L2 | 規劃 planned |
修改租戶的會員等級 |
lightup.coupon.read |
tenant | L2 | 規劃 planned |
讀取租戶的優惠券與使用紀錄 |
lightup.coupon.write |
tenant | L2 | 規劃 planned |
建立與修改租戶的優惠券 |
lightup.product.read |
tenant | L2 | 規劃 planned |
讀取租戶的商品、價格與分類 |
lightup.product.write |
tenant | L2 | 規劃 planned |
建立與修改租戶的商品、價格與分類 |
lightup.inventory.read |
tenant | L2 | 規劃 planned |
讀取租戶商品的庫存與可售數量 |
lightup.inventory.write |
tenant | L2 | 規劃 planned |
調整租戶商品的庫存 |
lightup.order.list |
tenant | L2 | 規劃 planned |
列出並讀取租戶的所有訂單(不限本應用程式建立的) |
lightup.order.update |
tenant | L2 | 規劃 planned |
修改租戶的訂單:備註、付款前的品項與出貨狀態 |
lightup.order.refund |
tenant | L2 | 規劃 planned |
為租戶已付款的訂單全額或部分退款 |
lightup.cart.read |
tenant | L2 | 規劃 planned |
讀取租戶客戶尚未結帳的購物車 |
lightup.invoice.read |
tenant | L2 | 規劃 planned |
讀取租戶訂單開立的發票 |
lightup.invoice.write |
tenant | L2 | 規劃 planned |
開立、作廢與折讓租戶的發票 |
lightup.payment.read |
tenant | L2 | 規劃 planned |
讀取租戶訂單的付款交易紀錄 |
lightup.subscription.read |
tenant | L2 | 規劃 planned |
讀取租戶的訂閱方案與客戶的訂閱 |
lightup.subscription.write |
tenant | L2 | 規劃 planned |
建立、修改與取消客戶的訂閱 |
lightup.course.read |
tenant | L2 | 規劃 planned |
讀取租戶的課程、單元與報名 |
lightup.course.write |
tenant | L2 | 規劃 planned |
建立與修改租戶的課程與單元 |
lightup.course.progress.read |
tenant | L2 | 規劃 planned |
讀取租戶學員的學習進度 |
lightup.offering.read |
tenant | L2 | 規劃 planned |
讀取租戶可預約的項目與時段 |
lightup.offering.write |
tenant | L2 | 規劃 planned |
建立與修改租戶可預約的項目與時段 |
lightup.resource.read |
tenant | L2 | 規劃 planned |
讀取租戶可預約的資源:場地、人員與設備 |
lightup.resource.write |
tenant | L2 | 規劃 planned |
建立與修改租戶可預約的資源 |
lightup.reservation.read |
tenant | L2 | 規劃 planned |
讀取租戶的預約 |
lightup.reservation.create |
tenant | L2 | 規劃 planned |
替租戶的客戶建立預約 |
lightup.reservation.update |
tenant | L2 | 規劃 planned |
修改與確認租戶的預約 |
lightup.reservation.cancel |
tenant | L2 | 規劃 planned |
取消租戶的預約 |
lightup.reservation.transfer |
tenant | L2 | 規劃 planned |
把預約改到別的時段或別的客戶 |
lightup.checkin.write |
tenant | L2 | 規劃 planned |
記錄租戶預約的報到 |
lightup.form.read |
tenant | L2 | 規劃 planned |
讀取租戶的表單與題目 |
lightup.form.record.read |
tenant | L2 | 規劃 planned |
讀取租戶表單收到的填答 |
lightup.form.record.write |
tenant | L2 | 規劃 planned |
修改租戶表單的填答 |
lightup.form.submit |
tenant | L2 | 規劃 planned |
替租戶的客戶送出表單填答 |
lightup.line.message.send |
tenant | L2 | 規劃 planned |
以租戶的 LINE 官方帳號傳訊息給客戶 |
lightup.line.broadcast |
tenant | L2 | 規劃 planned |
對租戶的 LINE 受眾群發訊息 |
lightup.line.audience.read |
tenant | L2 | 規劃 planned |
讀取租戶的 LINE 受眾 |
lightup.line.audience.write |
tenant | L2 | 規劃 planned |
建立與修改租戶的 LINE 受眾 |
lightup.message.send |
tenant | L2 | 規劃 planned |
以單一呼叫經 LINE、簡訊或 email 傳訊息給租戶的客戶,由平台選擇管道 |
lightup.email.template.read |
tenant | L2 | 規劃 planned |
讀取租戶的 email 範本 |
lightup.email.template.write |
tenant | L2 | 規劃 planned |
建立與修改租戶的 email 範本 |
lightup.execution_plan.read |
tenant | L2 | 規劃 planned |
讀取租戶的排程發送計畫與結果 |
lightup.execution_plan.write |
tenant | L2 | 規劃 planned |
建立與修改租戶的排程發送計畫 |
lightup.execution_plan.execute |
tenant | L2 | 規劃 planned |
執行、放行與重試租戶的排程發送計畫 |
lightup.chatroom.read |
tenant | L2 | 規劃 planned |
讀取租戶的客服對話與訊息 |
lightup.chatroom.message.send |
tenant | L2 | 規劃 planned |
在租戶的客服對話中傳送訊息 |
lightup.chatroom.assign |
tenant | L2 | 規劃 planned |
把租戶的客服對話指派給同仁 |
lightup.calendar.read |
tenant | L2 | 規劃 planned |
讀取租戶的行事曆與事件 |
lightup.calendar.write |
tenant | L2 | 規劃 planned |
在租戶的行事曆建立與修改事件 |
lightup.calendar.busy.read |
tenant | L2 | 規劃 planned |
讀取租戶同仁的忙碌時段(不含事件內容) |
lightup.file.read |
tenant | L2 | 規劃 planned |
讀取租戶的檔案 |
lightup.file.write |
tenant | L2 | 規劃 planned |
上傳與刪除租戶的檔案 |
lightup.link.read |
tenant | L2 | 規劃 planned |
讀取租戶的短網址與點擊數 |
lightup.link.write |
tenant | L2 | 規劃 planned |
建立與修改租戶的短網址 |
lightup.task.read |
tenant | L2 | 規劃 planned |
讀取租戶的任務卡 |
lightup.task.write |
tenant | L2 | 規劃 planned |
建立與修改租戶的任務卡 |
lightup.page.read |
tenant | L2 | 規劃 planned |
讀取租戶的前台頁面 |
lightup.page.write |
tenant | L2 | 規劃 planned |
建立與修改租戶前台頁面的草稿 |
lightup.page.publish |
tenant | L2 | 規劃 planned |
發佈租戶的前台頁面 |
lightup.automation.flow.read |
tenant | L2 | 規劃 planned |
讀取租戶的自動化流程 |
lightup.automation.flow.write |
tenant | L2 | 規劃 planned |
建立與修改租戶的自動化流程 |
lightup.automation.flow.publish |
tenant | L2 | 規劃 planned |
發佈與封存租戶的自動化流程 |
lightup.ledger.read |
tenant | L2 | 規劃 planned |
讀取租戶的會計帳:科目、傳票與餘額 |
lightup.report.read |
tenant | L2 | 規劃 planned |
讀取租戶的報表 |
lightup.report.export |
tenant | L2 | 規劃 planned |
把租戶的報表匯出成檔案 |
lightup.analytics.revenue.read |
tenant | L2 | 規劃 planned |
讀取租戶的營收與商品銷售報表(彙總) |
lightup.analytics.traffic.read |
tenant | L2 | 預覽 preview |
讀取租戶的網站流量與結帳漏斗報表(彙總,僅機器流程) |
lightup.analytics.ads.read |
tenant | L2 | 規劃 planned |
讀取租戶的廣告花費與成效報表(彙總) |
lightup.analytics.customers.read |
tenant | L2 | 規劃 planned |
讀取租戶的顧客成長與留存報表(彙總) |
lightup.analytics.messaging.read |
tenant | L2 | 規劃 planned |
讀取租戶的訊息量與送達報表(彙總) |
lightup.analytics.support.read |
tenant | L2 | 規劃 planned |
讀取租戶的客服量與回覆時間報表(彙總,不含個別同仁) |
lightup.analytics.loyalty.read |
tenant | L2 | 規劃 planned |
讀取租戶的點數與會員報表(彙總) |
lightup.analytics.lms.read |
tenant | L2 | 規劃 planned |
讀取租戶的課程進度報表(彙總) |
lightup.analytics.engagement.read |
tenant | L2 | 規劃 planned |
讀取租戶的表單填寫與短網址報表(彙總) |
lightup.settings.read |
tenant | L2 | 規劃 planned |
讀取租戶的公開設定 |
lightup.order.create、lightup.order.read、lightup.order.cancel 是 2026-10-17 加入的預覽能力,只限機器流程(client_credentials),操作與錯誤細節見訂單(預覽)。
lightup.tag.read、lightup.person.resolve、lightup.line.target 是 2026-10-19 加入的預覽能力,同樣只限機器流程;lightup.tag.write、lightup.tag.define 同日以規劃加入,2026-10-26 轉為預覽,同樣只限機器流程。標籤成員的寫入(lightup.tag.write)在租戶的身分切換完成之前一律回 409 tag_writes_not_open,切換完成之前不要開始寫入;建立標籤(lightup.tag.define)不受這個限制。見標籤與顧客(預覽)。
lightup.line.message_group.read 也是 2026-10-19 加入的預覽能力,只限機器流程:以 id 或完整名稱讀取租戶的 LINE 訊息組。見LINE 訊息組(預覽)。
lightup.person.profile.read 是 2026-10-25 加入的預覽能力,只限機器流程:以 id 讀取租戶指名客戶的名字、姓氏、顯示名稱、生日與性別(POST /v1/persons:profiles)。見標籤與顧客(預覽)。
其餘五項自 2026-10-05 起為正式。
可用狀態(availability)
| 狀態 | 意義 |
|---|---|
規劃 planned |
只存在於目錄,不會出現在可呼叫的路徑上 |
預覽 preview |
契約已定案、實作已上線可呼叫;但尚未適用 ga 的支援與棄用保證,欄位與行為仍可能調整(調整會照版本與棄用公告) |
正式 ga |
正式支援,適用相容與棄用政策 |
狀態轉換(planned → preview → ga)不算 API 升版,但一定會如實標在這一頁與變更紀錄。
方案等級
min_plan 是這項能力需要的最低租戶方案等級(L1/L2/L3)。有效能力是四層的交集:
有效能力 = 租戶方案上限
∩ 租戶對這支應用的 grant
∩ service account/使用者當次授權
∩ 資源政策(例如「這個租戶對這個人有沒有有效關係」)
任何一層縮水,能力就縮水。方案升級不會自動放大既有 grant:升級之後仍要重新核准才拿得到新增的能力。
每項能力對應的操作
| 能力 | 操作 |
|---|---|
lightup.profile.self.read |
GET /v1/me |
lightup.person.read |
GET /v1/persons/{personId} |
lightup.person.metadata.read |
GET /v1/persons/{personId}/extensionsGET /v1/persons/{personId}/extensions/{extensionId} |
lightup.person.metadata.write |
PUT /v1/persons/{personId}/extensions/{extensionId}DELETE /v1/persons/{personId}/extensions/{extensionId} |
lightup.tenant.info.read |
GET /v1/tenant |
lightup.order.create |
POST /v1/orders |
lightup.order.read |
GET /v1/orders/{orderId} |
lightup.order.cancel |
POST /v1/orders/{orderId}/cancel |
lightup.tag.read |
GET /v1/tags/{tagId}/membersPOST /v1/persons:tagsPOST /v1/tags:lookupPOST /v1/categories:lookup |
lightup.person.resolve |
POST /v1/persons:resolve |
lightup.line.target |
POST /v1/line-targets |
lightup.tag.write |
PUT /v1/persons/{personId}/tags/{tagId}DELETE /v1/persons/{personId}/tags/{tagId}POST /v1/tags/{tagId}/members:addPOST /v1/tags/{tagId}/members:remove |
lightup.tag.define |
POST /v1/tags |
lightup.line.message_group.read |
GET /v1/line-message-groupsGET /v1/line-message-groups/{groupId} |
lightup.person.profile.read |
POST /v1/persons:profiles |
lightup.person.wards.read |
GET /v1/persons/{personId}/wards |
lightup.person.contact.read |
— |
lightup.person.search |
— |
lightup.person.list |
— |
lightup.person.write |
— |
lightup.person.wards.write |
— |
lightup.person.marketing_consent.read |
— |
lightup.person.marketing_consent.write |
— |
lightup.audience.read |
— |
lightup.audience.write |
— |
lightup.membership.read |
— |
lightup.membership.write |
— |
lightup.loyalty.read |
— |
lightup.loyalty.points.write |
— |
lightup.loyalty.tier.write |
— |
lightup.coupon.read |
— |
lightup.coupon.write |
— |
lightup.product.read |
— |
lightup.product.write |
— |
lightup.inventory.read |
— |
lightup.inventory.write |
— |
lightup.order.list |
— |
lightup.order.update |
— |
lightup.order.refund |
— |
lightup.cart.read |
— |
lightup.invoice.read |
— |
lightup.invoice.write |
— |
lightup.payment.read |
— |
lightup.subscription.read |
— |
lightup.subscription.write |
— |
lightup.course.read |
— |
lightup.course.write |
— |
lightup.course.progress.read |
— |
lightup.offering.read |
— |
lightup.offering.write |
— |
lightup.resource.read |
— |
lightup.resource.write |
— |
lightup.reservation.read |
— |
lightup.reservation.create |
— |
lightup.reservation.update |
— |
lightup.reservation.cancel |
— |
lightup.reservation.transfer |
— |
lightup.checkin.write |
— |
lightup.form.read |
— |
lightup.form.record.read |
— |
lightup.form.record.write |
— |
lightup.form.submit |
— |
lightup.line.message.send |
— |
lightup.line.broadcast |
— |
lightup.line.audience.read |
— |
lightup.line.audience.write |
— |
lightup.message.send |
— |
lightup.email.template.read |
— |
lightup.email.template.write |
— |
lightup.execution_plan.read |
— |
lightup.execution_plan.write |
— |
lightup.execution_plan.execute |
— |
lightup.chatroom.read |
— |
lightup.chatroom.message.send |
— |
lightup.chatroom.assign |
— |
lightup.calendar.read |
— |
lightup.calendar.write |
— |
lightup.calendar.busy.read |
— |
lightup.file.read |
— |
lightup.file.write |
— |
lightup.link.read |
— |
lightup.link.write |
— |
lightup.task.read |
— |
lightup.task.write |
— |
lightup.page.read |
— |
lightup.page.write |
— |
lightup.page.publish |
— |
lightup.automation.flow.read |
— |
lightup.automation.flow.write |
— |
lightup.automation.flow.publish |
— |
lightup.ledger.read |
— |
lightup.report.read |
— |
lightup.report.export |
— |
lightup.analytics.revenue.read |
— |
lightup.analytics.traffic.read |
GET /v1/analytics/traffic/queryGET /v1/analytics/traffic/metrics |
lightup.analytics.ads.read |
— |
lightup.analytics.customers.read |
— |
lightup.analytics.messaging.read |
— |
lightup.analytics.support.read |
— |
lightup.analytics.loyalty.read |
— |
lightup.analytics.lms.read |
— |
lightup.analytics.engagement.read |
— |
lightup.settings.read |
— |