LightUp 第三方 API 契約已定案・端點已上線 v1.0.0 · 707394544381

能力索引

能力(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}/extensions
GET /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}/members
POST /v1/persons:tags
POST /v1/tags:lookup
POST /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:add
POST /v1/tags/{tagId}/members:remove
lightup.tag.define POST /v1/tags
lightup.line.message_group.read GET /v1/line-message-groups
GET /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/query
GET /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 —