API 參考
本頁完全由版本化的 OpenAPI 文件產生,沒有手寫的端點說明。
契約版本 1.0.0,base URL https://api.lightup.tech/v1。
操作一覽
| 操作 | 需要的能力 | operationId |
|---|---|---|
POST https://auth.lightup.tech/oauth2/token |
— | issueToken |
POST https://auth.lightup.tech/oauth2/revoke |
— | revokeToken |
POST https://auth.lightup.tech/oauth2/introspect |
— | introspectToken |
GET https://auth.lightup.tech/oauth2/logout |
— | endSession |
POST https://auth.lightup.tech/oauth2/logout |
— | endSessionForm |
GET /v1/me |
lightup.profile.self.read |
getMe |
GET /v1/tenant |
lightup.tenant.info.read |
getTenant |
GET /v1/persons/{personId} |
lightup.person.read |
getPerson |
GET /v1/persons/{personId}/extensions |
lightup.person.metadata.read |
listPersonExtensions |
GET /v1/persons/{personId}/extensions/{extensionId} |
lightup.person.metadata.read |
getPersonExtension |
PUT /v1/persons/{personId}/extensions/{extensionId} |
lightup.person.metadata.write |
putPersonExtension |
DELETE /v1/persons/{personId}/extensions/{extensionId} |
lightup.person.metadata.write |
deletePersonExtension |
POST /v1/orders |
lightup.order.create |
createOrder |
GET /v1/orders/{orderId} |
lightup.order.read |
getOrder |
POST /v1/orders/{orderId}/cancel |
lightup.order.cancel |
cancelOrder |
GET /v1/tags/{tagId}/members |
lightup.tag.read |
listTagMembers |
POST /v1/persons:tags |
lightup.tag.read |
listPersonsTags |
POST /v1/tags:lookup |
lightup.tag.read |
lookupTags |
POST /v1/categories:lookup |
lightup.tag.read |
lookupTagCategories |
POST /v1/persons:resolve |
lightup.person.resolve |
resolvePersons |
POST /v1/persons:profiles |
lightup.person.profile.read |
readPersonProfiles |
GET /v1/analytics/traffic/query |
lightup.analytics.traffic.read |
queryTrafficAnalytics |
GET /v1/analytics/traffic/metrics |
lightup.analytics.traffic.read |
listTrafficAnalyticsMetrics |
GET /v1/persons/{personId}/wards |
lightup.person.wards.read |
listPersonWards |
POST /v1/line-targets |
lightup.line.target |
listLineTargets |
PUT /v1/persons/{personId}/tags/{tagId} |
lightup.tag.write |
putPersonTag |
DELETE /v1/persons/{personId}/tags/{tagId} |
lightup.tag.write |
deletePersonTag |
POST /v1/tags/{tagId}/members:add |
lightup.tag.write |
addTagMembers |
POST /v1/tags/{tagId}/members:remove |
lightup.tag.write |
removeTagMembers |
POST /v1/tags |
lightup.tag.define |
createTag |
GET /v1/line-message-groups |
lightup.line.message_group.read |
findLineMessageGroups |
GET /v1/line-message-groups/{groupId} |
lightup.line.message_group.read |
getLineMessageGroup |
POST https://auth.lightup.tech/oauth2/token
operationId issueToken 能力 不需要(這裡是取得 token 的地方)
這個端點不在 API host 上。 完整網址就是上面那一個,沒有
/v1前綴。
換取 access token。不需要 Bearer token(這是取得 token 的地方), client 自己的認證放在表單或 Basic 標頭裡。
v1 支援的 grant
grant_type |
用途 | 得到的 profile | client 認證 |
|---|---|---|---|
client_credentials |
機器/背景 | workload |
client_secret(confidential) |
authorization_code |
使用者本人授權完成後換 token | self |
PKCE code_verifier+(confidential 另帶 secret) |
refresh_token |
續期使用者 token | self |
同上 |
三種 grant 都已上線。client_credentials 只在部署開啟第三方整合時才被接受,
discovery 的 grant_types_supported 也只在那時公告它(ADR-004 D3);沒開時
/oauth2/token 對它回 unsupported_grant_type。
client 認證方式
client_secret_post(放表單,如下方 schema)或 client_secret_basic
(Authorization: Basic base64(client_id:client_secret))。public client
兩者都不用,只靠 PKCE。
不會回什麼
client_credentials不回refresh_token(機器到期直接再換一張,ADR-004 D3)- 不回
id_token給資源存取用。就算流程拿到id_token,它只能用來驗身分; 拿去打 API 會被擋(typ不是at+jwt)
冪等與重試
authorization_code 與 refresh_token 都是一次性的。 重送同一個
code 或已消耗的 refresh_token 會得到 invalid_grant,而且重放
refresh 會殺掉整個 token family(嚴格 rotation,第三方不放寬)。
逾時後不要盲目重試——重新走一次流程。client_credentials 沒有這個問題,
可以安全重試。
限流
這個端點有自己的限流,與 API 的 tenant/account 雙層限流分開。
超過回 429,看 Retry-After。
請求 body
application/x-www-form-urlencoded,schema TokenRequest,必填。
範例 clientCredentials — 機器:client_credentials
{
"grant_type": "client_credentials",
"client_id": "tp_asiauni_rehab",
"client_secret": "<機器憑證,不要寫進版本控制>",
"scope": "lightup.person.read lightup.person.metadata.write"
}
範例 authorizationCode — 使用者:authorization_code + PKCE
{
"grant_type": "authorization_code",
"client_id": "tp_kidpro_parentapp",
"code": "<授權流程回傳的一次性 code>",
"code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
"redirect_uri": "https://app.example.com/callback"
}
範例 refreshToken — 使用者:續期
{
"grant_type": "refresh_token",
"client_id": "tp_kidpro_parentapp",
"refresh_token": "<上一次拿到的 refresh token>"
}
回應
| 狀態 | 說明 |
|---|---|
| 200 | 已發出 token |
| 400 | RFC 6749 §5.2 的 token 錯誤。注意它用 error 而不是本 API |
| 401 | 用 client_secret_basic 時 client 認證失敗。 |
| 429 | token 端點限流。看 Retry-After。 |
200 範例
範例 workload — client_credentials(無 refresh_token)
{
"access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCJ9...",
"token_type": "Bearer",
"expires_in": 900,
"scope": "lightup.person.read lightup.person.metadata.write"
}
範例 self — authorization_code(有 refresh_token)
{
"access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCJ9...",
"token_type": "Bearer",
"expires_in": 900,
"scope": "lightup.profile.self.read",
"refresh_token": "v1.MnR..."
}
400 範例
範例 unsupported
{
"error": "unsupported_grant_type",
"error_description": "client_credentials is not enabled on this deployment"
}
範例 invalidScope
{
"error": "invalid_scope",
"error_description": "requested scope is not granted to this application"
}
範例 tenantSuspended — 租戶被停權(機器可讀的 error_description)
{
"error": "invalid_grant",
"error_description": "tenant_suspended",
"message": "invalid grant: tenant_suspended"
}
POST https://auth.lightup.tech/oauth2/revoke
operationId revokeToken 能力 不需要(這裡是取得 token 的地方)
這個端點不在 API host 上。 完整網址就是上面那一個,沒有
/v1前綴。
RFC 7009 token revocation。撤銷你自己這個 client 的 refresh token。
它做什麼、不做什麼
| 撤掉 | 這張 refresh token 所屬的整個 token family(同一條 rotation 鏈) |
| 不會撤掉 | 同一個使用者在其他 client 上的 token |
| 不會結束 | 使用者在 auth.lightup.tech 上的登入(session 仍在) |
| 不會送出 | back-channel logout(這是你自己發起的動作,不是登出事件) |
| 在途 access token | 仍有效到自己的 exp(最長 15 分) |
要「把使用者登出」而不只是丟掉自己的 refresh token,用
https://auth.lightup.tech/oauth2/logout(RP-Initiated Logout)——那一條會結束
租戶 session,並對這顆 session 上所有第三方 client 送 back-channel logout。
⚠️ /oauth2/logout 綁瀏覽器:請求若不是來自持有那顆 session 的瀏覽器,
使用者會先看到確認頁。所以從伺服器端呼叫它不會靜默結束 session——想在後端
丟掉自己存的憑證,用的就是這裡的 revoke。它的 post_logout_redirect_uri 也只
接受 logout 登記裡的精確值,不符是 400 錯誤頁且使用者不會被登出。
租戶怎麼決定
以 client 登記的租戶為準。 tp_ client 的租戶由它自己的登記記錄決定,與
token 端點是同一條解析;不由 redirect_uri 的網域決定,也不由請求裡的任何
參數決定——你不需要(也不能)指定租戶。
client 認證
client_secret_basic 或 client_secret_post,擇一;兩者同時出現是 400。
public client 只帶 client_id。
回應
依 RFC 7009,成功一律 200 且無 body。token 不存在、已過期、或屬於別的 client,同樣是 200 且不做事——不會告訴你那張 token 存不存在。所以這個端點 天然冪等,逾時可以安全重試。
請求 body
application/x-www-form-urlencoded,schema object,必填。
範例 revoke — 撤銷自己的 refresh token
{
"token": "<上一次拿到的 refresh token>",
"token_type_hint": "refresh_token",
"client_id": "tp_kidpro_parentapp",
"client_secret": "<client 憑證,不要寫進版本控制>"
}
回應
| 狀態 | 說明 |
|---|---|
| 200 | 已撤銷,或那張 token 本來就不在(RFC 7009 不區分)。無 body。 |
| 400 | 請求形狀不對,或同時用了兩種 client 認證方式。 |
| 401 | client 認證失敗(invalid_client)。 |
POST https://auth.lightup.tech/oauth2/introspect
operationId introspectToken 能力 不需要(這裡是取得 token 的地方)
這個端點不在 API host 上。 完整網址就是上面那一個,沒有
/v1前綴。
RFC 7662 token introspection。這是判斷「使用者的登入現在還算不算有效」的權威 來源——back-channel logout 是 best effort,不可當成唯一的撤權訊號:通知是 至多一次(平台在結束 session 與送出之間重啟就不會補送),而且送信的連線 當下會判斷解析到的位址,落在私有位址就不送(登記時通過的 URI 也一樣, 因為登記檢查字面值、送出檢查當下解析到的 IP;一個名稱解析出多個位址時,只要有 一個被封鎖就整個不連)。
誰可以呼叫
| 條件 | 不符時 |
|---|---|
已啟用(enabled)的第三方 client |
401 invalid_client |
| confidential client(有 client secret) | 401 invalid_client。public client 沒有可認證的東西,一律不准 |
client_secret_basic 或 client_secret_post,擇一 |
兩者同時出現是 401 invalid_client |
可以查什麼
只能查自己的 token。 你自己這個 client 的 access token 或 refresh token 才會
回 active: true;別人的 token、ID token、格式不對的字串,一律
{"active": false}——不會告訴你它屬於誰、也不會告訴你它存不存在。
非 active 不分原因
{"active": false} 涵蓋全部:不存在、已過期、已消耗、已撤銷、屬於別人、
背後的租戶 session 已結束。刻意不細分,細分等於幫呼叫端做探測。
fail-closed
讀不到或判不完(Couchbase/授權端錯誤、逾時)→ 503 temporarily_unavailable,
絕不回 active: true。呼叫端也要 fail-closed:判不了就當作不可用。
沒有快取
每次都是即時讀取。撤權寫入成功後,下一次 introspect 就是 active: false。
限流
與登入共用 per-IP 限流,超過回 429 slow_down。
一個實用場景:refresh 結果未知
refresh 呼叫逾時而不知道有沒有成功時,不可重送同一張 refresh token(重送 =
reuse = 竊用訊號,會撤掉整個 family 並且結束整顆登入)。改成拿舊的那張來
introspect:active: true 表示那次 refresh 沒生效、可以安全重送;
active: false 表示已消耗或已撤,請使用者重新登入。
請求 body
application/x-www-form-urlencoded,schema object,必填。
範例 introspect — 查自己發出去的 access token
{
"token": "<要檢查的 token>",
"token_type_hint": "access_token",
"client_id": "tp_kidpro_parentapp",
"client_secret": "<client 憑證,不要寫進版本控制>"
}
回應
| 狀態 | 說明 |
|---|---|
| 200 | 已判定。active: true 帶完整欄位;active: false 只有這一個欄位。 |
| 400 | 請求 body 解不開(不是合法的 form 編碼)。error 是 invalid_request。 |
| 401 | client 認證失敗,或這個 client 不准 introspect(不是第三方、 |
| 404 | 第三方功能在本部署尚未開啟,這條路由不存在。error 是 not_found。 |
| 429 | 限流(與登入共用 per-IP 額度),error 是 slow_down。 |
| 503 | 現在判不了(讀取失敗或逾時)。這不是 active: false, |
200 範例
範例 active — 有效的 access token
{
"active": true,
"sub": "psn_01j8m4k2r7e9v3xq5w8n0tzh6p",
"sid": "8f14e45fea5c4f7a9a1b2c3d4e5f6a7b",
"client_id": "tp_kidpro_parentapp",
"token_type": "Bearer",
"exp": 1790000900,
"iat": 1790000000,
"auth_time": 1789999500,
"acr": "urn:lightup:loa:1",
"tenant_id": "ten_01j8m4k2r7e9v3xq5w8n0tzh6p",
"scope": "lightup.profile.self.read"
}
範例 activeRefresh — 有效的 refresh token
{
"active": true,
"sub": "psn_01j8m4k2r7e9v3xq5w8n0tzh6p",
"sid": "8f14e45fea5c4f7a9a1b2c3d4e5f6a7b",
"client_id": "tp_kidpro_parentapp",
"token_type": "refresh_token",
"exp": 1790086400,
"iat": 1790000000,
"auth_time": 1789999500,
"acr": "urn:lightup:loa:2",
"tenant_id": "ten_01j8m4k2r7e9v3xq5w8n0tzh6p",
"scope": "lightup.profile.self.read"
}
範例 inactive — 無效(不分原因)
{
"active": false
}
GET https://auth.lightup.tech/oauth2/logout
operationId endSession 能力 不需要(這裡是取得 token 的地方)
這個端點不在 API host 上。 完整網址就是上面那一個,沒有
/v1前綴。
OpenID Connect RP-Initiated Logout 1.0。把使用者的瀏覽器導到這裡(不是從伺服器 端呼叫):結束使用者在平台上的那次登入,並對同一次登入上所有第三方 client 送 back-channel logout(包含發起的你自己)。
這是瀏覽器端點:回應一律是 HTML 頁面或 302 轉址,不是 JSON。參數放在
query string;同一組參數也可以用 POST 表單送(見下一個操作)。
它做什麼、不做什麼
| 結束 | 使用者在 auth.lightup.tech 上的那次登入(id_token_hint 的 sid 指向的 session) |
| 送出 | back-channel logout 給這次登入上所有登記了 back-channel URI 的第三方 client |
| 之後 | 綁在這次登入上的 token,introspect 一律回 active: false,refresh 也換不到新 token |
| 在途 access token | 仍有效到自己的 exp(最長 15 分) |
只想丟掉自己這個 app 存的 refresh token、不把使用者登出,用 /oauth2/revoke。
id_token_hint 必填
沒有 hint 的請求一律 400——否則任何網頁都能把人登出。hint 必須是平台簽發的
ID token(ES256、簽章金鑰在平台 JWKS 上);已過期的也接受(規格允許)。
帶了 client_id 時必須等於 hint 的 aud,不符是 400。
post_logout_redirect_uri
- 可省略。省略時登出照做,使用者停在平台的「已登出」頁。
- 帶了就必須精確等於這個 client 的 logout 登記裡的
postLogoutRedirectUris之一(多一個尾斜線、多一個 query 都不算相符)。不符、或這個 client 根本沒有 logout 登記 → 400 錯誤頁,而且使用者不會被登出。 - 相符時登出後 302 回到這個 URI;帶了
state會以statequery 參數附加回去。
瀏覽器綁定:不是同一個瀏覽器會先看到確認頁
發出請求的瀏覽器若持有 hint 指向的那次登入(它的 session cookie 推得出同一個
sid),直接登出。否則先回一張確認頁:一張 POST 回 /oauth2/logout 的表單,
把 id_token_hint/client_id/post_logout_redirect_uri/state 原樣帶著,
外加一次性的 confirm 欄位與對應的 __Host-oidc_logout_confirm cookie
(300 秒);使用者按下確認才真的登出。所以從伺服器端呼叫這條路由不會靜默結束
session,只會拿到確認頁。
順序:post_logout_redirect_uri 的驗證在綁定檢查之前——帶了未登記的 redirect
會直接拿到 400 錯誤頁,不會先看到確認頁。
冪等
對已經結束的登入再登出一次不是錯誤:結果仍是「已登出」頁或 302(瀏覽器不持有 那次登入時,一樣先經過確認頁)。back-channel logout 不會再送第二次。
第一方 hint
hint 若是 LightUp 第一方產品的 ID token,這條路由也接受,但不結束任何 session,
也沒有確認頁;post_logout_redirect_uri 不符時顯示「已登出」頁而不是 400。這個放寬
不適用於第三方 hint。
每個回應都帶
Cache-Control: no-store、Referrer-Policy: no-referrer,以及
Content-Security-Policy: default-src 'none'; form-action 'self'; frame-ancestors 'none'
(頁面不能被嵌進 iframe)。
參數
| 名稱 | 位置 | 必填 | 型別 | 說明 |
|---|---|---|---|---|
id_token_hint |
query | 是 | string | 平台簽發給這個 client 的 ID token。已過期的也接受。 |
client_id |
query | 否 | string | 可省略;帶了就必須等於 hint 的 aud。 |
post_logout_redirect_uri |
query | 否 | string | 可省略;帶了就必須精確等於 logout 登記裡的值之一。 format uri |
state |
query | 否 | string | 可省略;導回時以 state query 參數附加回去。 |
回應
| 狀態 | 說明 |
|---|---|
| 200 | 「已登出」頁,或確認頁(登入還沒結束,等使用者按下確認)。 |
| 302 | 已登出,導回已登記的 post_logout_redirect_uri。 |
| 400 | 錯誤頁(「無法處理這次登出請求」),使用者沒有被登出。 |
| 404 | 第三方功能在本部署尚未開啟,這條路由不存在(錯誤頁)。 |
| 503 | 錯誤頁:平台現在處理不了這次登出,請稍後重試。 |
POST https://auth.lightup.tech/oauth2/logout
operationId endSessionForm 能力 不需要(這裡是取得 token 的地方)
這個端點不在 API host 上。 完整網址就是上面那一個,沒有
/v1前綴。
與 GET /oauth2/logout 同一個端點、同一套規則,參數改放
application/x-www-form-urlencoded 表單。平台自己的確認頁就是用這個形式送回來的
(多帶一個 confirm 欄位);你的應用也可以用自動送出的表單把使用者帶過來。
body 不是合法的表單編碼時回 400 錯誤頁。其餘行為見 GET /oauth2/logout。
請求 body
application/x-www-form-urlencoded,schema object,必填。
範例 logout — 登出並導回已登記的頁面
{
"id_token_hint": "<登入時拿到的 ID token>",
"client_id": "tp_kidpro_parentapp",
"post_logout_redirect_uri": "https://app.example.com/signed-out",
"state": "af0ifjsldkj"
}
回應
| 狀態 | 說明 |
|---|---|
| 200 | 「已登出」頁,或確認頁(登入還沒結束,等使用者按下確認)。 |
| 302 | 已登出,導回已登記的 post_logout_redirect_uri。 |
| 400 | 錯誤頁(「無法處理這次登出請求」),使用者沒有被登出。 |
| 404 | 第三方功能在本部署尚未開啟,這條路由不存在(錯誤頁)。 |
| 503 | 錯誤頁:平台現在處理不了這次登出,請稍後重試。 |
GET /v1/me
operationId getMe 能力 lightup.profile.self.read
能力:lightup.profile.self.read(方案 L1 起)
回傳這張 token 自己的身分,不是任意人的資料。v1 有兩種 profile:
| token profile | subjectType |
subjectId |
actor |
|---|---|---|---|
self |
person |
本人 psn_… |
本人 acc_… |
workload |
service_account |
acc_…(kind=service) |
同 subjectId |
機器 token 呼叫這支不會「變成某個使用者」:workload 的答案就是 service
account 自己。機器能讀一群人的資料,不代表平台驗證過任何一位終端使用者
(計畫 §4.1)。
冪等:GET,天然冪等。不計入寫入額度。
回應
| 狀態 | 說明 |
|---|---|
| 200 | OK |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
200 範例
範例 self — 使用者本人的 token
{
"subjectType": "person",
"subjectId": "psn_01j8m4k2r7e9v3xq5w8n0tza6b",
"tenantId": "ten_0cqqg39h2199x8fd5kf58s0eb5",
"clientId": "tp_kidpro_parentapp",
"scopes": [
"lightup.profile.self.read",
"lightup.person.metadata.read"
],
"actor": {
"accountId": "acc_01j8m4k2r7e9v3xq5w8n0tzb7c"
}
}
範例 workload — 機器 token
{
"subjectType": "service_account",
"subjectId": "acc_01j8m4k2r7e9v3xq5w8n0tzc8d",
"tenantId": "ten_0cqqg39h2199x8fd5kf58s0eb5",
"clientId": "tp_asiauni_rehab",
"scopes": [
"lightup.person.read",
"lightup.person.metadata.write"
],
"actor": {
"accountId": "acc_01j8m4k2r7e9v3xq5w8n0tzc8d"
}
}
GET /v1/tenant
operationId getTenant 能力 lightup.tenant.info.read
能力:lightup.tenant.info.read(方案 L1 起)
租戶由 token 決定,不由參數決定。沒有 GET /v1/tenants/{id}:
一張 token 只能看自己的租戶(計畫 §9 驗收矩陣第 1 列)。
回傳的是識別欄位,不是租戶設定。不含方案細節、聯絡人、網域設定、 社群 provider、LDAP 或任何秘密。
沒有 state 欄位(v1 刻意不給)
這支不回租戶的營運狀態。停權租戶不需要用一個欄位來表達: 它的 token 在簽發與每次判權兩處都已經被擋下,所以呼叫端 根本拿不到能成功呼叫的 token——狀態會以 401/403 的形式出現, 而不是以一個要自己判讀的欄位出現。
少一個欄位也少一種錯誤用法:如果 Gateway 在上游沒給值時填一個預設的
active,partner 會據此決定要不要送出寫入——那正是這種欄位最容易
造成的傷害。v1 的選擇是不給,而不是猜。
冪等:GET。
回應
| 狀態 | 說明 |
|---|---|
| 200 | OK |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
200 範例
範例 default
{
"tenantId": "ten_0cqqg39h2199x8fd5kf58s0eb5",
"displayName": "KidPro"
}
GET /v1/persons/{personId}
operationId getPerson 能力 lightup.person.read
能力:lightup.person.read(方案 L2 起)
只回三個欄位:personId、displayName、createdAt。
沒有 email、沒有手機、沒有生日、沒有關係、沒有訂單、沒有任何 channel identity。
要更多欄位是新的能力,要新的 grant,不是在這裡加參數。
這支不回 metadata(計畫 §6:「一般主檔 GET 不順便吐出全部 metadata」)。
metadata 走 /v1/persons/{personId}/extensions/...,且需要另外的能力。
授權:除了 capability 之外,Amygdala 還會確認這個租戶對這個人有有效關係。 關係不成立時回 404,不是 403 —— caller 不應該從錯誤碼推斷這個 person 是否存在 (ADR-004 D9)。
冪等:GET。
參數
| 名稱 | 位置 | 必填 | 型別 | 說明 |
|---|---|---|---|---|
personId |
path | 是 | PersonTypeId | 人員的 TypeID(psn_…)。不可自行拼裝或解析;只使用平台給過你的值 (ADR-003 §1、計畫 §6)。 pattern ^psn_[0-9a-hjkmnp-tv-z]{26}$ |
回應
| 狀態 | 說明 |
|---|---|
| 200 | OK |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 404 | 資源不存在,或存在但呼叫端連它存不存在都不該知道。 |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
200 範例
範例 default
{
"personId": "psn_01j8m4k2r7e9v3xq5w8n0tza6b",
"displayName": "王小明",
"createdAt": "2025-03-11T02:14:07Z"
}
GET /v1/persons/{personId}/extensions
operationId listPersonExtensions 能力 lightup.person.metadata.read
能力:lightup.person.metadata.read(方案 L2 起)
只列出呼叫端自己擁有的 extension。 同租戶的別的 app 寫的 extension
不會出現在這裡,也不會被計入 total(計畫 §9 驗收矩陣第 2 列)。
分頁是有界的:limit 預設 20、上限 100。用 cursor 取下一頁。
沒有「全部拉下來」的參數,也沒有任意 JSON 查詢(計畫 §6:v1 只有 key lookup + 有界分頁)。
冪等:GET。
參數
| 名稱 | 位置 | 必填 | 型別 | 說明 |
|---|---|---|---|---|
personId |
path | 是 | PersonTypeId | 人員的 TypeID(psn_…)。不可自行拼裝或解析;只使用平台給過你的值 (ADR-003 §1、計畫 §6)。 pattern ^psn_[0-9a-hjkmnp-tv-z]{26}$ |
limit |
query | 否 | integer | 每頁筆數。預設 20,上限 100。超過上限 → 422。 預設 20;最小 1;最大 100 |
cursor |
query | 否 | string | 上一頁回應的 nextCursor。不透明字串,不要解析;換版本後形狀可能改變。 最長 512 |
回應
| 狀態 | 說明 |
|---|---|
| 200 | OK |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 404 | 資源不存在,或存在但呼叫端連它存不存在都不該知道。 |
| 422 | 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。 |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
200 範例
範例 default
{
"items": [
{
"extensionId": "rehab_progress",
"schemaVersion": 3,
"etag": "\"17\"",
"updatedAt": "2026-09-20T08:31:55Z",
"updatedBy": "tp_asiauni_rehab"
}
],
"nextCursor": null
}
GET /v1/persons/{personId}/extensions/{extensionId}
operationId getPersonExtension 能力 lightup.person.metadata.read
能力:lightup.person.metadata.read(方案 L2 起)
回應帶 ETag。要改這筆資料,把 ETag 原封不動放進 If-Match。
404 的三種情況回答一樣:extension 未登記、這個 app 不是它的 owner、 資料不存在。錯誤碼不透露資源是否存在(ADR-004 D9)。
冪等:GET。
參數
| 名稱 | 位置 | 必填 | 型別 | 說明 |
|---|---|---|---|---|
personId |
path | 是 | PersonTypeId | 人員的 TypeID(psn_…)。不可自行拼裝或解析;只使用平台給過你的值 (ADR-003 §1、計畫 §6)。 pattern ^psn_[0-9a-hjkmnp-tv-z]{26}$ |
extensionId |
path | 是 | ExtensionId | 登記時由平台配發的 extension id。不可用會改名的功能名稱當身分(計畫 §6)。 未登記或不屬於呼叫端 → 404。 pattern ^[a-z][a-z0-9_]{2,63}$ |
回應
| 狀態 | 說明 |
|---|---|
| 200 | OK |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 404 | 資源不存在,或存在但呼叫端連它存不存在都不該知道。 |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
200 範例
範例 default
{
"extensionId": "rehab_progress",
"personId": "psn_01j8m4k2r7e9v3xq5w8n0tza6b",
"schemaVersion": 3,
"etag": "\"17\"",
"data": {
"lastSessionAt": "2026-09-19T09:00:00Z",
"completedUnits": 12
},
"createdAt": "2026-04-02T01:00:00Z",
"updatedAt": "2026-09-20T08:31:55Z",
"updatedBy": "tp_asiauni_rehab"
}
PUT /v1/persons/{personId}/extensions/{extensionId}
operationId putPersonExtension 能力 lightup.person.metadata.write
能力:lightup.person.metadata.write(方案 L2 起)
整筆取代,不是 patch:data 就是新的完整內容。
並行控制(必讀)
每個 PUT 必須恰好帶一個前置條件標頭,而且是 RFC 9110 的標準語意, 沒有自訂延伸:
- 建立用
If-None-Match: *— 「只有在它還不存在時才寫」(RFC 9110 §13.1.2) - 更新用
If-Match: "<etag>"— 「只有在它還是這一版時才寫」(§13.1.1)
If-Match 不接受 *(那是 DELETE 才有的用法)。兩個都不帶、或兩個
都帶,一律 428 precondition_required——本 API 沒有「無條件覆寫」這個操作,
因為那正是遺失更新的來源。
| 情境 | 送什麼 | 結果 |
|---|---|---|
| 建立新的一筆 | If-None-Match: * |
201 |
| 建立但它已經存在 | If-None-Match: * |
409 already_exists |
| 更新既有一筆 | If-Match: "<etag>" |
200 |
| 更新但版本已被別人改掉 | If-Match: "<舊 etag>" |
409 revision_conflict |
| 更新但那筆已被刪除 | If-Match: "<etag>" |
404 |
| 兩個都沒帶,或兩個都帶 | — | 428 precondition_required |
兩個 client 同時寫,後到的那個會拿到 409,不會覆蓋前一個(計畫 §6)。
正確處理方式:重新 GET、合併、帶新的 ETag 重送。
ℹ️ 為什麼建立衝突是 409 而不是 412。 RFC 9110 對失敗的前置條件給的是
412;本 API 刻意把它收斂成 409,讓「你和別人撞上了」只有一個狀態碼,
client 的錯誤處理只要分辨 Problem.error(already_exists vs
revision_conflict)就夠,不必同時處理 409 與 412 兩條路徑。
428 則保留給「你根本沒表明意圖」,那是 client 的 bug,不是衝突。
額度(計畫 §6/§7)
| 限制 | 值 | 超過時 |
|---|---|---|
單筆 data 大小 |
16 KiB | 413 |
| 每 tenant 每 extension 筆數 | 50,000 | 422 quota_exceeded |
| 每 tenant extension 數 | 20 | 422 quota_exceeded |
額度判定與寫入在同一交易內完成,所以大量並行寫入不會衝破上限 (計畫 §7「交易內處理並行寫入的額度競爭」)。 額度滿不會刪任何既有資料;讀取與刪除照常可用。
這裡不能放什麼
照片、逐題事件、無界成長的列表,以及任何被當成 permission、餘額、購買權益 或身份綁定的欄位(計畫 §6)。平台不會因為 metadata 說了什麼而授予任何權限。
冪等
同樣的 data + 同樣的 If-Match 重送:第一次成功後 ETag 就變了,
第二次會得到 409。要安全重試,重讀後再送。
計量以 x-request-id 為 idempotency key,重試不重複計量。
參數
| 名稱 | 位置 | 必填 | 型別 | 說明 |
|---|---|---|---|---|
personId |
path | 是 | PersonTypeId | 人員的 TypeID(psn_…)。不可自行拼裝或解析;只使用平台給過你的值 (ADR-003 §1、計畫 §6)。 pattern ^psn_[0-9a-hjkmnp-tv-z]{26}$ |
extensionId |
path | 是 | ExtensionId | 登記時由平台配發的 extension id。不可用會改名的功能名稱當身分(計畫 §6)。 未登記或不屬於呼叫端 → 404。 pattern ^[a-z][a-z0-9_]{2,63}$ |
If-Match |
header | 否 | string | 更新既有資料時使用,值是上次讀到的 ETag(RFC 9110 §13.1.1)。 required: false 是因為 OpenAPI 無法表達「If-Match 與 If-None-Match 恰好擇一」。這不代表可以兩個都不帶——兩個都不帶或兩個都帶都是 428 precondition_required。建立新資料請改用 If-None-Match: *。 不接受 *(schema 就擋掉)。If-Match: * 在 RFC 裡的意思是 「只要它存在」,那是 DELETE 的用法,拿來建立資料會是錯的。 pattern ^"[^"]+"$ |
If-None-Match |
header | 否 | string | 建立新資料時使用,唯一合法值是 *,意思是「只有在它還不存在時才寫」 (RFC 9110 §13.1.2)。 它已經存在 → 409 already_exists(不是 412,見 PUT 的說明)。 required: false 的理由同 If-Match:兩者恰好擇一,OpenAPI 表達不了, 所以由伺服器以 428 執行。 pattern ^\*$ |
請求 body
application/json,schema PersonExtensionWrite,必填。
範例 default
{
"schemaVersion": 3,
"data": {
"lastSessionAt": "2026-09-22T09:00:00Z",
"completedUnits": 13
}
}
回應
| 狀態 | 說明 |
|---|---|
| 200 | 已更新 |
| 201 | 已建立 |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 404 | 資源不存在,或存在但呼叫端連它存不存在都不該知道。 |
| 409 | 你和別人撞上了。沒有任何東西被寫入。 兩種: |
| 413 | 單筆 data 超過 16 KiB。縮小內容,或把大東西放在你自己的資料庫 |
| 422 | 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。 |
| 428 | 這個寫入沒有表明它的前置條件(RFC 6585 §3)。 |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
DELETE /v1/persons/{personId}/extensions/{extensionId}
operationId deletePersonExtension 能力 lightup.person.metadata.write
能力:lightup.person.metadata.write(方案 L2 起)
冪等:已經不存在也回 204(計畫 §6「刪除可冪等」)。
If-Match 必填(required: true,schema 驗得到):
If-Match: "<etag>"— 只在還是那一版時才刪。版本不符 → 409revision_conflictIf-Match: *— 不管哪一版都刪(RFC 9110 §13.1.1 的標準*語意: 「只要它存在」。這裡合用,因為刪除本來就只對存在的東西有意義)- 省略 → 428
precondition_required
「已經不存在」與「存在但版本不符」不同:前者 204(冪等),後者 409。
DELETE 不看 If-None-Match;送了會被忽略。
刪除釋放筆數額度,但不會回填任何歷史;要保留請先匯出。
參數
| 名稱 | 位置 | 必填 | 型別 | 說明 |
|---|---|---|---|---|
personId |
path | 是 | PersonTypeId | 人員的 TypeID(psn_…)。不可自行拼裝或解析;只使用平台給過你的值 (ADR-003 §1、計畫 §6)。 pattern ^psn_[0-9a-hjkmnp-tv-z]{26}$ |
extensionId |
path | 是 | ExtensionId | 登記時由平台配發的 extension id。不可用會改名的功能名稱當身分(計畫 §6)。 未登記或不屬於呼叫端 → 404。 pattern ^[a-z][a-z0-9_]{2,63}$ |
If-Match |
header | 是 | string | 必填(required: true,schema 驗得到;DELETE 只有這一個前置條件標頭, 不存在擇一的問題)。 - "<etag>" — 只刪那一版;版本不符 → 409 revision_conflict - * — 不論版本都刪(RFC 9110 §13.1.1 的標準語意:「只要它存在」) 省略 → 428 precondition_required。已經不存在 → 204(冪等)。 pattern `^(* |
回應
| 狀態 | 說明 |
|---|---|
| 204 | 已刪除,或原本就不存在(冪等) |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 404 | 資源不存在,或存在但呼叫端連它存不存在都不該知道。 |
| 409 | 你和別人撞上了。沒有任何東西被寫入。 兩種: |
| 428 | 這個寫入沒有表明它的前置條件(RFC 6585 §3)。 |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
POST /v1/orders
operationId createOrder 能力 lightup.order.create
能力:lightup.order.create(方案 L2 起)·可用狀態:預覽(preview)
為租戶的一位客戶建立未付款訂單。價格一律取自商品目錄:請求沒有單價欄位,
帶了未知欄位會被 422 schema_invalid 拒絕。
只限機器流程:必須是 workload token(service account)。使用者本人的 self
token 會得到 403 profile_not_supported。
冪等(必讀)
Idempotency-Key 必填,1–200 個可見 ASCII 字元(0x21–0x7E),不可有空白。
缺漏或格式不對 → 422 schema_invalid,而且在判權之前就回。
| 情境 | 結果 |
|---|---|
| 第一次送出這個 key | 201,建立新訂單 |
| 同一個 key、同一份請求,24 小時內重送 | 200,回傳原來那張訂單,不會建立第二張 |
| 同一個 key、不同的請求內容 | 409 idempotency_key_reused |
| 同一個 key 的上一次請求還在處理中 | 409 request_in_progress,帶 Retry-After: 2 |
網路逾時而不知道有沒有建立成功:用同一個 key、同一份請求重送即可,不會重複建單。
付款期限
expiresAt 選填(RFC 3339)。有給的話必須晚於現在、且不超過現在起 10 年,否則
422 schema_invalid。沒給的話,訂單會在 30 分鐘後自動取消。
買家與操作者
customerPersonId必填,是psn_開頭的 TypeID(見PersonTypeId)。只使用平台給過你的值。X-LightUp-Operator選填,只是註記:記錄是哪位員工操作。Gateway 會交給 amygdala 簽進下游 token 供稽核;它不參與授權,也不會被轉送到下游。
參數
| 名稱 | 位置 | 必填 | 型別 | 說明 |
|---|---|---|---|---|
Idempotency-Key |
header | 是 | string | 建立訂單的冪等鍵:1–200 個可見 ASCII 字元(0x21–0x7E),不可有空白。 同一個 key 重送同一份請求,回原來那張訂單(200);同一個 key 用在不同的請求 上,回 409 idempotency_key_reused。缺漏或格式不對 → 422 schema_invalid,在判權之前。 pattern ^[!-~]{1,200}$;最長 200 |
X-LightUp-Operator |
header | 否 | string | 選填。聲明「是哪位員工操作」,例如 usr_…; name=%E7%8E%8B。只是註記:Gateway 原樣交給 amygdala 簽進下游 token 供稽核;不參與授權,也不被轉送。 必須是非空白、≤ 256 位元組、不含控制字元的字串;否則 422 schema_invalid。 最長 256 |
請求 body
application/json,schema OrderCreateRequest,必填。
範例 makeup — 兩個品項、附屬性、設定付款期限
{
"customerPersonId": "psn_01j8m4k2r7e9v3xq5w8n0tza6b",
"items": [
{
"productId": "ae886b43-83d5-4ce7-8a0f-7ffc7daa39da",
"quantity": 1,
"attributes": {
"leaveId": "lv_example_0001",
"leaveSku": "example-leave-sku",
"makeupSku": "example-makeup-sku"
}
},
{
"productId": "3f0c2a6e-9b1d-4e51-8c7a-2d5f8e1b9a04",
"quantity": 2
}
],
"remark": "補課費",
"expiresAt": "2026-10-20T18:00:00+08:00"
}
回應
| 狀態 | 說明 |
|---|---|
| 200 | 同一個 Idempotency-Key、同一份請求的重送,回傳原來那張訂單 |
| 201 | 已建立新訂單 |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 409 | 訂單操作與現況衝突。沒有任何東西被寫入或改變。 三種: |
| 422 | 請求格式對,但內容不可接受。沒有任何東西被寫入。 兩種: |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
GET /v1/orders/{orderId}
operationId getOrder 能力 lightup.order.read
能力:lightup.order.read(方案 L2 起)·可用狀態:預覽(preview)
回傳這支應用程式自己建立的訂單。別的 client 建立的、別的租戶的、或根本不存在的
訂單,一律回 404 not_found,不分辨(ADR-004 D9)。
orderId 形狀不合(不是 1–128 個 [A-Za-z0-9_-])也回 404,而且在判權之前就回。
回應只有 Order 定義的欄位;訂單上其他內部欄位不會出現。金額是 JSON 數字。
冪等:GET,天然冪等。
參數
| 名稱 | 位置 | 必填 | 型別 | 說明 |
|---|---|---|---|---|
orderId |
path | 是 | string | 訂單 id,就是建立時回傳的 orderId。1–128 個 [A-Za-z0-9_-];形狀不合 → 404。 pattern ^[A-Za-z0-9_-]+$;最長 128 |
回應
| 狀態 | 說明 |
|---|---|
| 200 | OK |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 404 | 資源不存在,或存在但呼叫端連它存不存在都不該知道。 |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
POST /v1/orders/{orderId}/cancel
operationId cancelOrder 能力 lightup.order.cancel
能力:lightup.order.cancel(方案 L2 起)·可用狀態:預覽(preview)
只能取消未付款且仍可取消的訂單,成功回 200 與取消後的 Order。
不可取消(已取消、已付款、或已進入不可取消的狀態)→ 409 order_not_cancellable。
detail 是下游訂單服務的代碼與訊息,格式 "{code}: {message}",例如
ORDER_ALREADY_CANCELLED: …、ORDER_NOT_CANCELLABLE: …、ORDER_CANCEL_PENDING_OPERATOR: …。
409 時沒有任何東西被改變。
別的 client 建立的、別的租戶的、或不存在的訂單 → 404 not_found。
冪等:重送已取消的訂單會得到 409 order_not_cancellable(ORDER_ALREADY_CANCELLED),
不是 200。要確認現況,讀 GET /v1/orders/{orderId} 的 status。
參數
| 名稱 | 位置 | 必填 | 型別 | 說明 |
|---|---|---|---|---|
orderId |
path | 是 | string | 訂單 id,就是建立時回傳的 orderId。1–128 個 [A-Za-z0-9_-];形狀不合 → 404。 pattern ^[A-Za-z0-9_-]+$;最長 128 |
請求 body
application/json,schema OrderCancelRequest,必填。
範例 default
{
"reason": "客戶來電取消"
}
回應
| 狀態 | 說明 |
|---|---|
| 200 | 已取消,回傳取消後的訂單 |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 404 | 資源不存在,或存在但呼叫端連它存不存在都不該知道。 |
| 409 | 訂單操作與現況衝突。沒有任何東西被寫入或改變。 三種: |
| 422 | 請求格式對,但內容不可接受。沒有任何東西被寫入。 兩種: |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
GET /v1/tags/{tagId}/members
operationId listTagMembers 能力 lightup.tag.read
能力:lightup.tag.read(方案 L2 起)·可用狀態:預覽(preview)
回傳帶著這個標籤的客戶,一次一頁,依 person id 排序。回應有 next 時,把它原樣放進下一次的
after 取下一頁;沒有 next 就是最後一頁。
只限機器流程:必須是 workload token(service account)。使用者本人的 self
token 會得到 403 profile_not_supported。
tagId形狀不合(不是 1–64 個[A-Za-z0-9._-])→ 404,在判權之前就回。- 標籤不屬於這張 token 的租戶,或不存在 → 404
not_found,不分辨。 after不是psn_TypeID、limit不在 1–100,或帶了未知、重複的查詢參數 → 422schema_invalid, 在判權之前。
冪等:GET,天然冪等。
參數
| 名稱 | 位置 | 必填 | 型別 | 說明 |
|---|---|---|---|---|
tagId |
path | 是 | TagId | 標籤 id,來自 POST /v1/tags:lookup、POST /v1/persons:tags 或 POST /v1/tags 的回應。 1–64 個 [A-Za-z0-9._-];形狀不合 → 404,在判權之前。 pattern ^[A-Za-z0-9._-]{1,64}$;最長 64 |
after |
query | 否 | PersonTypeId | 上一頁回應的 next(一個 psn_ TypeID)。省略就從第一頁開始。不是 psn_ TypeID → 422 schema_invalid。 pattern ^psn_[0-9a-hjkmnp-tv-z]{26}$ |
limit |
query | 否 | integer | 每頁筆數,1–100。省略時是 50。超出範圍 → 422 schema_invalid。 預設 50;最小 1;最大 100 |
回應
| 狀態 | 說明 |
|---|---|
| 200 | OK |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 404 | 資源不存在,或存在但呼叫端連它存不存在都不該知道。 |
| 422 | 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。 |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
200 範例
範例 default
{
"members": [
{
"personId": "psn_01j8m4k2r7e9v3xq5w8n0tza6b",
"addedAt": "2026-10-19T09:30:00Z"
}
],
"next": "psn_01j8m4k2r7e9v3xq5w8n0tza6b"
}
POST /v1/persons:tags
operationId listPersonsTags 能力 lightup.tag.read
能力:lightup.tag.read(方案 L2 起)·可用狀態:預覽(preview)
一次最多 100 位客戶,回傳每一位帶著的標籤與加上的時間。
只限機器流程(workload token);使用者本人的 token 會得到 403 profile_not_supported。
personIds 是 1–100 個 psn_ TypeID。只要有一個不合格,整個請求就是 422
schema_invalid(在判權之前):清單建錯了就不是「一半對」。
冪等:唯讀,可以安全重送。
請求 body
application/json,schema PersonIdsRequest,必填。
範例 default
{
"personIds": [
"psn_01j8m4k2r7e9v3xq5w8n0tza6b"
]
}
回應
| 狀態 | 說明 |
|---|---|
| 200 | OK |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 422 | 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。 |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
POST /v1/tags:lookup
operationId lookupTags 能力 lightup.tag.read
能力:lightup.tag.read(方案 L2 起)·可用狀態:預覽(preview)
一次最多 100 個名稱(每個 1–200 字元),每個名稱回一個結果:
outcome |
意思 |
|---|---|
FOUND |
剛好一個標籤叫這個名稱,tagId 就是它 |
NOT_FOUND |
沒有標籤叫這個名稱 |
AMBIGUOUS |
不只一個標籤叫這個名稱(通常在不同分類下)。帶 categoryNodeId 限定分類再查一次 |
categoryNodeId 選填,只在那一個分類下找;它來自 POST /v1/categories:lookup。
只限機器流程(workload token)。
冪等:唯讀,可以安全重送。
請求 body
application/json,schema TagLookupRequest,必填。
範例 default
{
"names": [
"永和 週六"
],
"categoryNodeId": "node-7"
}
回應
| 狀態 | 說明 |
|---|---|
| 200 | OK |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 422 | 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。 |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
POST /v1/categories:lookup
operationId lookupTagCategories 能力 lightup.tag.read
能力:lightup.tag.read(方案 L2 起)·可用狀態:預覽(preview)
一次最多 100 個名稱(每個 1–200 字元),每個名稱回一個結果,outcome 與
POST /v1/tags:lookup 相同(FOUND/NOT_FOUND/AMBIGUOUS)。FOUND 時帶
categoryNodeId;AMBIGUOUS 時帶 candidates(每一個叫這個名稱的分類 id)。
categoryNodeId 就是 POST /v1/tags:lookup 與 POST /v1/tags 要的那個值。
只限機器流程(workload token)。
冪等:唯讀,可以安全重送。
請求 body
application/json,schema CategoryLookupRequest,必填。
範例 default
{
"names": [
"上課時段"
]
}
回應
| 狀態 | 說明 |
|---|---|
| 200 | OK |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 422 | 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。 |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
POST /v1/persons:resolve
operationId resolvePersons 能力 lightup.person.resolve
能力:lightup.person.resolve(方案 L2 起)·可用狀態:預覽(preview)
一次最多 500 個舊客戶 id(每個 1–128 字元),每個回一個結果:
outcome |
意思 |
|---|---|
RESOLVED |
對應到一位客戶,personId 就是他 |
NOT_FOUND |
這個租戶沒有這個舊 id 的對應 |
AMBIGUOUS |
平台存的對應彼此不一致(例如對到兩位客戶)。不要替它選邊,也不要對它發送行銷訊息 |
INVALID |
這個值不是任何一種拼法的使用者 id 或 person id |
只限機器流程(workload token)。
冪等:唯讀,可以安全重送。
請求 body
application/json,schema PersonResolveRequest,必填。
範例 default
{
"legacyIds": [
"5d7c0b0e-8a33-4b1c-9b0e-2f2f0b0e8a33"
]
}
回應
| 狀態 | 說明 |
|---|---|
| 200 | OK |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 422 | 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。 |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
POST /v1/persons:profiles
operationId readPersonProfiles 能力 lightup.person.profile.read
能力:lightup.person.profile.read(方案 L2 起)·可用狀態:預覽(preview)
一次最多 500 個 id(每個 1–128 字元),每個回一個結果。每個 id 可以是裸的舊客戶 UUID,
也可以是 psn_ person id,平台分辨的方式與 POST /v1/persons:resolve 完全相同。
沒有列出全部客戶的形式:要讀誰,就要逐一指名。
outcome |
意思 |
|---|---|
FOUND |
找到一位客戶,帶 personId 與五個基本資料欄位 |
NOT_FOUND |
這個租戶沒有這個 id 的客戶 |
AMBIGUOUS |
平台存的對應彼此不一致(例如對到兩位客戶)。不要替它選邊 |
INVALID |
這個值不是任何一種拼法的使用者 id 或 person id |
只有 FOUND 帶資料:personId 與 givenName、familyName、displayName、birthDate、
gender 五個欄位。這五個欄位一定出現,沒有值時是 null。其他結果只有 id 與 outcome。
- 新系統建立的孩子常常只有
displayName,名字與姓氏都是null;givenName、familyName都沒有值時,請改用displayName顯示。 - 平台逐欄檢查:性別不在
male/female/other/unknown之內、生日不是真實存在的YYYY-MM-DD、名稱去掉前後空白後為空或超過 200 字元,一律回null,不會讓整批失敗。 回傳的名稱是去掉前後空白之後的值;生日必須剛好是YYYY-MM-DD的寫法(例如2019-4-07回null)。 - 不回傳電話、email 或地址。
只限機器流程(workload token)。授權服務每次呼叫記一筆稽核紀錄。
冪等:唯讀,可以安全重送。
請求 body
application/json,schema PersonProfilesRequest,必填。
範例 default
{
"ids": [
"5d7c0b0e-8a33-4b1c-9b0e-2f2f0b0e8a33",
"psn_01j8m4k2r7e9v3xq5w8n0tza6c"
]
}
回應
| 狀態 | 說明 |
|---|---|
| 200 | OK |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 422 | 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。 |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
200 範例
範例 default
{
"profiles": [
{
"id": "5d7c0b0e-8a33-4b1c-9b0e-2f2f0b0e8a33",
"outcome": "FOUND",
"personId": "psn_01j8m4k2r7e9v3xq5w8n0tza6b",
"givenName": "小明",
"familyName": "王",
"displayName": "王小明",
"birthDate": "2019-04-07",
"gender": "male"
},
{
"id": "psn_01j8m4k2r7e9v3xq5w8n0tza6c",
"outcome": "FOUND",
"personId": "psn_01j8m4k2r7e9v3xq5w8n0tza6c",
"givenName": null,
"familyName": null,
"displayName": "新孩子",
"birthDate": null,
"gender": null
}
]
}
GET /v1/analytics/traffic/query
operationId queryTrafficAnalytics 能力 lightup.analytics.traffic.read
能力:lightup.analytics.traffic.read(方案 L2 起)·可用狀態:預覽(preview)
讀取一個指標。回傳的都是彙總:次數與比例,不含金額,也不含任何個人資料,網址路徑中的識別碼會換成 :id。依渠道的訂單與營收不在這一項。
meta.notes寫著這批數字的限制(例如「網站流量從某日起才有」),請一併讀取;meta.isPartial為true表示有部分資料讀取失敗。- 不認得的參數、缺
topic或metric、範圍過長(最長 400 天;day粒度最長 92 天)都回 422schema_invalid。不存在的指標回 404。 - 每次最多 5,000 列,超過回 422,請縮小範圍。
- 請把用量控制在同時 2 個查詢、每分鐘 30 次以內,超過回 429 並帶
Retry-After。這是可以放心使用的範圍,不是精確的上限。這組操作是給每日報表用的,不適合輪詢。
只限機器流程(workload token)。
冪等:唯讀,可以安全重送。
參數
| 名稱 | 位置 | 必填 | 型別 | 說明 |
|---|---|---|---|---|
topic |
query | 是 | string | 指標所屬的主題:traffic 或 checkout。可用的組合見 GET /v1/analytics/traffic/metrics。 最長 64 |
metric |
query | 是 | string | 指標名稱,例如 channels。 最長 64 |
granularity |
query | 否 | string | 時間粒度,例如 day。指標支援哪些粒度,見 GET /v1/analytics/traffic/metrics。 最長 64 |
start |
query | 否 | string | 範圍起點(含),租戶時區的日期,YYYY-MM-DD。要和 end 一起給;和 quickRange 二選一。 最長 64 |
end |
query | 否 | string | 範圍終點(不含),租戶時區的日期,YYYY-MM-DD。 最長 64 |
quickRange |
query | 否 | string | 常用範圍,和 start/end 二選一。 列舉:this_month_to_date、last_month、same_month_last_year、this_quarter_to_date、last_quarter、this_year_to_date、last_year、last_12_months |
compare |
query | 否 | string | 比較期,預設 none。 列舉:none、previous_period、previous_year |
dimension |
query | 否 | string | 只有少數指標用得到,可用的值見 GET /v1/analytics/traffic/metrics。 最長 64 |
topN |
query | 否 | string | 只對有排名的指標有效。 最長 64 |
回應
| 狀態 | 說明 |
|---|---|
| 200 | OK |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 404 | 資源不存在,或存在但呼叫端連它存不存在都不該知道。 |
| 422 | 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。 |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
200 範例
範例 default
{
"meta": {
"topic": "traffic",
"metric": "channels",
"granularity": "day",
"timezone": "Asia/Taipei",
"currency": "TWD",
"rangeStart": "2026-11-05",
"rangeEnd": "2026-11-06",
"isPartial": false,
"generatedAt": "2026-11-06T01:00:00Z",
"notes": []
},
"schema": [
{
"name": "period",
"type": "string",
"semantic": "time",
"unit": ""
},
{
"name": "channel",
"type": "string",
"semantic": "dimension",
"unit": ""
},
{
"name": "sessions",
"type": "number",
"semantic": "measure",
"unit": "sessions"
}
],
"rows": [
{
"dimensions": {
"period": "2026-11-05",
"channel": "meta"
},
"measures": {
"sessions": 128
}
}
],
"series": []
}
GET /v1/analytics/traffic/metrics
operationId listTrafficAnalyticsMetrics 能力 lightup.analytics.traffic.read
能力:lightup.analytics.traffic.read(方案 L2 起)·可用狀態:預覽(preview)
列出這個領域開放的指標,以及每個指標支援的粒度、分組與量值。不接受任何參數。
只限機器流程(workload token)。
冪等:唯讀,可以安全重送。
回應
| 狀態 | 說明 |
|---|---|
| 200 | OK |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 404 | 資源不存在,或存在但呼叫端連它存不存在都不該知道。 |
| 422 | 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。 |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
200 範例
範例 default
{
"metrics": [
{
"topic": "traffic",
"metric": "channels",
"granularities": [
"day",
"week",
"month"
],
"groupBy": [
"period",
"channel"
],
"measures": [
"sessions"
]
}
]
}
GET /v1/persons/{personId}/wards
operationId listPersonWards 能力 lightup.person.wards.read
能力:lightup.person.wards.read(方案 L2 起)·可用狀態:預覽(preview)
一次查一位監護人,回傳他目前生效中的監護關係裡的孩子,每個孩子帶 personId 與
POST /v1/persons:profiles 相同的五個基本資料欄位:givenName、familyName、displayName、
birthDate、gender。五個欄位一定出現,沒有值時是 null,檢查規則也與
POST /v1/persons:profiles 相同。
- 只列生效中的關係:草稿(還沒生效)與已撤銷的監護關係不列出。
- 最多 50 個孩子。超過時只回前 50 個,並回
"truncated": true。 - 平台在租戶裡找不到這位監護人回 404;找到但沒有孩子回 200 與空的
wards。 - 不回傳電話、email 或地址,也不回傳監護關係本身的 id。
只限機器流程(workload token)。授權服務每次呼叫記一筆稽核紀錄。
冪等:唯讀,可以安全重送。
參數
| 名稱 | 位置 | 必填 | 型別 | 說明 |
|---|---|---|---|---|
personId |
path | 是 | string | 監護人:psn_ person id,或訂單 customerId 帶的裸 UUID(舊系統的拼法,同一個人)。 UUID 必須是帶連字號的 8-4-4-4-12 形式,大小寫皆可;其他形式回 404。 最長 128 |
回應
| 狀態 | 說明 |
|---|---|
| 200 | OK |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 404 | 資源不存在,或存在但呼叫端連它存不存在都不該知道。 |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
200 範例
範例 default
{
"guardian": {
"personId": "psn_01j8m4k2r7e9v3xq5w8n0tza6b"
},
"wards": [
{
"personId": "psn_01j8m4k2r7e9v3xq5w8n0tza6c",
"givenName": "小明",
"familyName": "王",
"displayName": "王小明",
"birthDate": "2019-04-07",
"gender": "male"
},
{
"personId": "psn_01j8m4k2r7e9v3xq5w8n0tza6d",
"givenName": null,
"familyName": null,
"displayName": "新孩子",
"birthDate": null,
"gender": null
}
],
"truncated": false
}
POST /v1/line-targets
operationId listLineTargets 能力 lightup.line.target
能力:lightup.line.target(方案 L2 起)·可用狀態:預覽(preview)
一次最多 100 位客戶。每位回一個結果;DELIVERABLE 時帶 lineUserId,
其他結果一律不帶。
lineUserId 是這位客戶在該租戶自己的 LINE 官方帳號下的 LINE user id:
只能用那一個官方帳號送訊息給他,換到別的官方帳號沒有意義。
outcome |
意思 |
|---|---|
DELIVERABLE |
可以送,lineUserId 是要送的對象 |
NO_LINE |
這位客戶沒有 LINE 身分 |
NOT_FOUND |
這個租戶沒有這個 id 的客戶 |
AMBIGUOUS |
這位客戶有不只一個 LINE id,或彼此不一致。平台不替你選,兩邊都不要送 |
BLOCKED |
這位客戶已被封鎖(例如員工在聊天室封鎖),不要送 |
UNSUBSCRIBED |
這位客戶取消訂閱,不要送 |
只限機器流程(workload token)。personIds 是 1–100 個 psn_ TypeID;有一個不合格就整個
422 schema_invalid。
冪等:唯讀,可以安全重送。結果反映當下的狀態,不要長期快取。
請求 body
application/json,schema PersonIdsRequest,必填。
範例 default
{
"personIds": [
"psn_01j8m4k2r7e9v3xq5w8n0tza6b"
]
}
回應
| 狀態 | 說明 |
|---|---|
| 200 | OK |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 422 | 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。 |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
200 範例
範例 default
{
"targets": [
{
"personId": "psn_01j8m4k2r7e9v3xq5w8n0tza6b",
"outcome": "DELIVERABLE",
"lineUserId": "U0123456789abcdef0123456789abcdef"
}
]
}
PUT /v1/persons/{personId}/tags/{tagId}
operationId putPersonTag 能力 lightup.tag.write
能力:lightup.tag.write(方案 L2 起)·可用狀態:預覽(preview)
租戶的身分切換完成之前,這個寫入一律被拒:回 409 tag_writes_not_open。這是狀態,不是權限,重試或重新授權都不會變;切換完成之前不要開始寫入標籤成員。
為一位客戶加上一個標籤。已經帶著 → 200 changed: false。
冪等(必讀)
Idempotency-Key 必填,而且必須是非 nil 的 UUID(與訂單的規則不同)。缺漏或不是 UUID →
422 schema_invalid,在判權之前。同一個 key 再送一次 → 200 replayed: true,不會再寫一次;
同一個 key 用在不同的寫入上 → 409 idempotency_key_reused。
其他
personId不是psn_TypeID、tagId形狀不合 → 404,在判權之前。- 客戶或標籤不屬於這個租戶 → 404
not_found。 - 該租戶的客戶在這裡還不能寫(身分切換尚未完成)→ 409
tag_writes_not_open。 - 這位客戶已被合併到另一位 → 409
person_merged。 - 這位客戶的標籤數已達上限 → 422
tag_limit_reached。
只限機器流程(workload token)。
參數
| 名稱 | 位置 | 必填 | 型別 | 說明 |
|---|---|---|---|---|
personId |
path | 是 | PersonTypeId | 人員的 TypeID(psn_…)。不可自行拼裝或解析;只使用平台給過你的值 (ADR-003 §1、計畫 §6)。 pattern ^psn_[0-9a-hjkmnp-tv-z]{26}$ |
tagId |
path | 是 | TagId | 標籤 id,來自 POST /v1/tags:lookup、POST /v1/persons:tags 或 POST /v1/tags 的回應。 1–64 個 [A-Za-z0-9._-];形狀不合 → 404,在判權之前。 pattern ^[A-Za-z0-9._-]{1,64}$;最長 64 |
Idempotency-Key |
header | 是 | string | 標籤成員寫入的冪等鍵:一個非 nil 的 UUID,只接受有連字號的 8-4-4-4-12 寫法,十六進位大小寫皆可 (平台以小寫保存)。無連字號、加大括號或 urn:uuid: 前綴的寫法一律 422 schema_invalid。 與建立訂單的 Idempotency-Key(1–200 個可見 ASCII)規則不同:這裡只接受 UUID, 因為下游把它當成這次寫入的 retry id。 同一個 key 重送同一個寫入是安全的,不會寫兩次;同一個 key 用在不同的寫入上 → 409 idempotency_key_reused,而且什麼都不寫。一個 key 綁定一個完整的請求:多一位或少一位客戶、 換標籤、換 provenance、同一批人先加後移,都是不同的寫入,所以加和移要用不同的 key; 同一批客戶只是順序不同或有重複,仍算同一個請求。缺漏、不是 UUID 或是全零 UUID → 422 schema_invalid,在判權之前。 pattern ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$;format uuid |
回應
| 狀態 | 說明 |
|---|---|
| 200 | 已處理(changed 說明這次有沒有真的加上) |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 404 | 資源不存在,或存在但呼叫端連它存不存在都不該知道。 |
| 409 | 標籤寫入與現況衝突。沒有任何東西被寫入。 三種新的代碼: |
| 422 | 標籤請求格式對,但內容不可接受。沒有任何東西被寫入。 兩種新的代碼: |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
DELETE /v1/persons/{personId}/tags/{tagId}
operationId deletePersonTag 能力 lightup.tag.write
能力:lightup.tag.write(方案 L2 起)·可用狀態:預覽(preview)
租戶的身分切換完成之前,這個寫入一律被拒:回 409 tag_writes_not_open。這是狀態,不是權限,重試或重新授權都不會變;切換完成之前不要開始寫入標籤成員。
移除一位客戶的一個標籤。本來就沒帶著 → 200 changed: false。
Idempotency-Key 必填,必須是非 nil 的 UUID;規則與 PUT 相同(同一個 key 重送 →
replayed: true;用在不同的寫入上 → 409 idempotency_key_reused)。404 與 409 的情況也與 PUT 相同。
只限機器流程(workload token)。
參數
| 名稱 | 位置 | 必填 | 型別 | 說明 |
|---|---|---|---|---|
personId |
path | 是 | PersonTypeId | 人員的 TypeID(psn_…)。不可自行拼裝或解析;只使用平台給過你的值 (ADR-003 §1、計畫 §6)。 pattern ^psn_[0-9a-hjkmnp-tv-z]{26}$ |
tagId |
path | 是 | TagId | 標籤 id,來自 POST /v1/tags:lookup、POST /v1/persons:tags 或 POST /v1/tags 的回應。 1–64 個 [A-Za-z0-9._-];形狀不合 → 404,在判權之前。 pattern ^[A-Za-z0-9._-]{1,64}$;最長 64 |
Idempotency-Key |
header | 是 | string | 標籤成員寫入的冪等鍵:一個非 nil 的 UUID,只接受有連字號的 8-4-4-4-12 寫法,十六進位大小寫皆可 (平台以小寫保存)。無連字號、加大括號或 urn:uuid: 前綴的寫法一律 422 schema_invalid。 與建立訂單的 Idempotency-Key(1–200 個可見 ASCII)規則不同:這裡只接受 UUID, 因為下游把它當成這次寫入的 retry id。 同一個 key 重送同一個寫入是安全的,不會寫兩次;同一個 key 用在不同的寫入上 → 409 idempotency_key_reused,而且什麼都不寫。一個 key 綁定一個完整的請求:多一位或少一位客戶、 換標籤、換 provenance、同一批人先加後移,都是不同的寫入,所以加和移要用不同的 key; 同一批客戶只是順序不同或有重複,仍算同一個請求。缺漏、不是 UUID 或是全零 UUID → 422 schema_invalid,在判權之前。 pattern ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$;format uuid |
回應
| 狀態 | 說明 |
|---|---|
| 200 | 已處理(changed 說明這次有沒有真的移除) |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 404 | 資源不存在,或存在但呼叫端連它存不存在都不該知道。 |
| 409 | 標籤寫入與現況衝突。沒有任何東西被寫入。 三種新的代碼: |
| 422 | 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。 |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
POST /v1/tags/{tagId}/members:add
operationId addTagMembers 能力 lightup.tag.write
能力:lightup.tag.write(方案 L2 起)·可用狀態:預覽(preview)
租戶的身分切換完成之前,這個寫入一律被拒:回 409 tag_writes_not_open。這是狀態,不是權限,重試或重新授權都不會變;切換完成之前不要開始寫入標籤成員。
一次最多 1000 位客戶。回應說明多少位這次加上(changed)、多少位本來就帶著(unchanged),
並逐一列出被略過的客戶與原因(skipped):
reason |
意思 |
|---|---|
missing |
這個租戶沒有這位客戶 |
not_canonical |
這位客戶已被合併到另一位;改用合併後的 person id |
tag_limit |
這位客戶的標籤數已達上限 |
provenance 選填:一個不透明的來源參照(例如規則 id、匯入批次 id),[A-Za-z0-9._:-],1–128 字元。
Idempotency-Key 必填,必須是非 nil 的 UUID。同一個 key、同一份請求重送是安全的;
同一個 key 用在不同的請求上 → 409 idempotency_key_reused。一個 key 綁定一個完整的請求:
多一位或少一位客戶、換標籤、換 provenance、先加後移都算不同的請求,所以加和移要用不同的 key;
同一批客戶只是順序不同或有重複,仍算同一個請求。
只限機器流程(workload token)。
參數
| 名稱 | 位置 | 必填 | 型別 | 說明 |
|---|---|---|---|---|
tagId |
path | 是 | TagId | 標籤 id,來自 POST /v1/tags:lookup、POST /v1/persons:tags 或 POST /v1/tags 的回應。 1–64 個 [A-Za-z0-9._-];形狀不合 → 404,在判權之前。 pattern ^[A-Za-z0-9._-]{1,64}$;最長 64 |
Idempotency-Key |
header | 是 | string | 標籤成員寫入的冪等鍵:一個非 nil 的 UUID,只接受有連字號的 8-4-4-4-12 寫法,十六進位大小寫皆可 (平台以小寫保存)。無連字號、加大括號或 urn:uuid: 前綴的寫法一律 422 schema_invalid。 與建立訂單的 Idempotency-Key(1–200 個可見 ASCII)規則不同:這裡只接受 UUID, 因為下游把它當成這次寫入的 retry id。 同一個 key 重送同一個寫入是安全的,不會寫兩次;同一個 key 用在不同的寫入上 → 409 idempotency_key_reused,而且什麼都不寫。一個 key 綁定一個完整的請求:多一位或少一位客戶、 換標籤、換 provenance、同一批人先加後移,都是不同的寫入,所以加和移要用不同的 key; 同一批客戶只是順序不同或有重複,仍算同一個請求。缺漏、不是 UUID 或是全零 UUID → 422 schema_invalid,在判權之前。 pattern ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$;format uuid |
請求 body
application/json,schema TagMembersAddRequest,必填。
範例 default
{
"personIds": [
"psn_01j8m4k2r7e9v3xq5w8n0tza6b"
],
"provenance": "rule:7"
}
回應
| 狀態 | 說明 |
|---|---|
| 200 | 已處理 |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 404 | 資源不存在,或存在但呼叫端連它存不存在都不該知道。 |
| 409 | 標籤寫入與現況衝突。沒有任何東西被寫入。 三種新的代碼: |
| 422 | 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。 |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
POST /v1/tags/{tagId}/members:remove
operationId removeTagMembers 能力 lightup.tag.write
能力:lightup.tag.write(方案 L2 起)·可用狀態:預覽(preview)
租戶的身分切換完成之前,這個寫入一律被拒:回 409 tag_writes_not_open。這是狀態,不是權限,重試或重新授權都不會變;切換完成之前不要開始寫入標籤成員。
一次最多 1000 位客戶。回應形狀與 members:add 相同(changed/unchanged/skipped)。
Idempotency-Key 必填,必須是非 nil 的 UUID;規則與 members:add 相同。
只限機器流程(workload token)。
參數
| 名稱 | 位置 | 必填 | 型別 | 說明 |
|---|---|---|---|---|
tagId |
path | 是 | TagId | 標籤 id,來自 POST /v1/tags:lookup、POST /v1/persons:tags 或 POST /v1/tags 的回應。 1–64 個 [A-Za-z0-9._-];形狀不合 → 404,在判權之前。 pattern ^[A-Za-z0-9._-]{1,64}$;最長 64 |
Idempotency-Key |
header | 是 | string | 標籤成員寫入的冪等鍵:一個非 nil 的 UUID,只接受有連字號的 8-4-4-4-12 寫法,十六進位大小寫皆可 (平台以小寫保存)。無連字號、加大括號或 urn:uuid: 前綴的寫法一律 422 schema_invalid。 與建立訂單的 Idempotency-Key(1–200 個可見 ASCII)規則不同:這裡只接受 UUID, 因為下游把它當成這次寫入的 retry id。 同一個 key 重送同一個寫入是安全的,不會寫兩次;同一個 key 用在不同的寫入上 → 409 idempotency_key_reused,而且什麼都不寫。一個 key 綁定一個完整的請求:多一位或少一位客戶、 換標籤、換 provenance、同一批人先加後移,都是不同的寫入,所以加和移要用不同的 key; 同一批客戶只是順序不同或有重複,仍算同一個請求。缺漏、不是 UUID 或是全零 UUID → 422 schema_invalid,在判權之前。 pattern ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$;format uuid |
請求 body
application/json,schema PersonIdsBatchRequest,必填。
範例 default
{
"personIds": [
"psn_01j8m4k2r7e9v3xq5w8n0tza6b"
]
}
回應
| 狀態 | 說明 |
|---|---|
| 200 | 已處理 |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 404 | 資源不存在,或存在但呼叫端連它存不存在都不該知道。 |
| 409 | 標籤寫入與現況衝突。沒有任何東西被寫入。 三種新的代碼: |
| 422 | 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。 |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
POST /v1/tags
operationId createTag 能力 lightup.tag.define
能力:lightup.tag.define(方案 L2 起)·可用狀態:預覽(preview)
建立標籤不受成員寫入的切換限制(tag_writes_not_open),租戶切換身分之前也可以呼叫。
在一個已經存在的標籤分類(categoryNodeId,來自 POST /v1/categories:lookup)下建立標籤。
分類不存在 → 422 category_not_found;分類請由租戶在後台建立。
同一個分類下同一個名稱只會有一個標籤,所以重送是安全的,不需要 Idempotency-Key:
| 情境 | 結果 |
|---|---|
| 這次建立了新標籤 | 201,created: true |
| 這個分類下已經有同名標籤 | 200,created: false,回傳既有那一個的 tagId |
| 這個名稱對應的標籤 id 已被一個後來改名或搬走的標籤占用 | 409 tag_name_conflict |
tagName 會先去掉前後空白,再檢查 1–100 字元、不含控制字元。description 去掉前後空白後為空,
視同沒給。
只限機器流程(workload token)。
請求 body
application/json,schema TagCreateRequest,必填。
範例 default
{
"tagName": "永和 週六",
"categoryNodeId": "node-7",
"backgroundColor": "#12AB9F"
}
回應
| 狀態 | 說明 |
|---|---|
| 200 | 這個分類下已有同名標籤,回傳它的 id |
| 201 | 已建立新標籤 |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 409 | 標籤寫入與現況衝突。沒有任何東西被寫入。 三種新的代碼: |
| 422 | 標籤請求格式對,但內容不可接受。沒有任何東西被寫入。 兩種新的代碼: |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
GET /v1/line-message-groups
operationId findLineMessageGroups 能力 lightup.line.message_group.read
能力:lightup.line.message_group.read(方案 L2 起)·可用狀態:預覽(preview)
回傳租戶的 LINE 訊息組中,去掉前後空白後的名稱與 name 完全相同的那些,依 id 排序,
最多 10 個。不是模糊搜尋:差一個字、多一個空格(中間的)都不算。
只限機器流程:必須是 workload token(service account)。使用者本人的 self
token 會得到 403 profile_not_supported。
- 查詢參數只能有一個
name,沒有其他參數;去掉前後空白後 1–200 個字元(以 Unicode 字元計)。 缺漏、重複、空白、太長,或帶了其他參數 → 422schema_invalid,在判權之前。 matched是回來的筆數(等於items的長度);truncated為true表示符合的不只這 10 個。- 一定要剛好一個時:
matched必須是 1、truncated必須是false,否則不要自己挑。
冪等:GET,天然冪等。
參數
| 名稱 | 位置 | 必填 | 型別 | 說明 |
|---|---|---|---|---|
name |
query | 是 | string | 要找的訊息組名稱。這個操作只收這一個查詢參數,而且只能出現一次。 去掉前後空白後比對, 必須 1–200 個字元(以 Unicode 字元計);否則 422 schema_invalid。 |
回應
| 狀態 | 說明 |
|---|---|
| 200 | OK(沒有符合的也是 200,matched 為 0) |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 422 | 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。 |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
200 範例
範例 default
{
"name": "永和 週六 10:00 課前影片",
"matched": 1,
"truncated": false,
"items": [
{
"id": "6f2d1c0e-9a77-4f39-9b1a-0b5d6a3e2f0c",
"name": "永和 週六 10:00 課前影片",
"updatedAt": "2026-10-18T09:30:15.250Z",
"messages": [
{
"type": "text",
"text": "明天見!",
"complete": true
},
{
"type": "video",
"originalContentId": "m-1",
"previewImageId": "m-2",
"complete": true
}
]
}
]
}
GET /v1/line-message-groups/{groupId}
operationId getLineMessageGroup 能力 lightup.line.message_group.read
能力:lightup.line.message_group.read(方案 L2 起)·可用狀態:預覽(preview)
回傳一個 LINE 訊息組:名稱、更新時間與每一則訊息的文字或媒體 id。
只限機器流程(workload token)。
groupId形狀不合(不是 1–64 個[A-Za-z0-9_-])→ 404,在判權之前就回。- 訊息組不存在,或屬於別的租戶 → 404
not_found,不分辨。
冪等:GET,天然冪等。
參數
| 名稱 | 位置 | 必填 | 型別 | 說明 |
|---|---|---|---|---|
groupId |
path | 是 | LineMessageGroupId | LINE 訊息組的 id,來自 GET /v1/line-message-groups?name=… 的回應。1–64 個 [A-Za-z0-9_-] (從舊系統搬來的 id 原樣保留,所以不一定是 UUID);形狀不合 → 404,在判權之前。 pattern ^[A-Za-z0-9_-]{1,64}$;最長 64 |
回應
| 狀態 | 說明 |
|---|---|
| 200 | OK |
| 401 | token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符 |
| 403 | token 有效,但現在不准做這件事。重試不會變成允許—— |
| 404 | 資源不存在,或存在但呼叫端連它存不存在都不該知道。 |
| 429 | 限流。限流有兩層:tenant 與 service account/使用者 |
| 503 | 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同: |
共用錯誤回應
Unauthorized
401 — token 本身不可用:沒帶、無效、過期、簽章錯、aud/iss/typ 不符
(例如把 ID token 或第一方 token 拿來用)。
error 一律是 invalid_token,不細分。 沒帶 token 與帶了壞 token
回同一個答案,aud 錯與簽章錯也回同一個答案——細分等於幫呼叫端
(包括攻擊者)確認哪一項才是錯的。真正的原因記在伺服器端,
用 x-request-id 查。
重新取得 token 再試。重試同一張 token 不會變成成功。
ℹ️ delegated 與 shared profile 的 token 不在這裡被擋:它們的簽章
是對的,會走完驗證再由授權決定拒絕,所以拿到的是
403 profile_not_supported。
範例 idTokenUsed — 拿 ID token 當 access token
{
"error": "invalid_token",
"message": "token is not an access token",
"requestId": "req_01j8m4k2r7e9v3xq5w8n0tzh2j"
}
Forbidden
403 — token 有效,但現在不准做這件事。重試不會變成允許—— 要改的是 grant、方案或請求本身。
error 是穩定代碼,逐字來自 Amygdala 的授權決定(ADR-004 D5)。
程式判斷用它,不要 parse message。
error |
意思 | 怎麼修 |
|---|---|---|
client_unknown |
這個 client id 不存在 | 重新登記 app |
client_disabled |
client 存在但已被停用(status=disabled)。與 client_unknown 分開:前者是「被關掉了」,後者是「從來沒有」,處理方式不同 |
tenant 管理員重新啟用。停用對在途 token 也立即生效——下一個請求就擋 |
actor_unknown |
token 沒有指出誰在操作:self 缺 actor_account_id,或 workload 帶的 actor_account_id 不等於 sub |
重新取一張 token。這代表簽發端有問題,請附 x-request-id 回報 |
tenant_suspended |
租戶被停權。與呼叫端是誰、請求哪一項能力都無關——整個租戶的第三方存取都停,讀寫皆然 | 租戶要先恢復。重試沒有用;即使換一張 token 也一樣,簽發端同樣會拒 |
tenant_not_enabled |
這個租戶的第三方整合沒有生效:該租戶的方案不含第三方整合,或租戶尚未在後台開啟它。講的是租戶這一側的狀態,與呼叫端是誰、請求哪一項能力無關。刻意不分辨是哪一個原因——對你來說下一步一樣,而分開講會洩漏客戶的方案等級 | 請洽該租戶的管理員。重試與換 token 都沒有用——簽發端對同一個租戶一樣拒(回 OAuth 的 invalid_client)。真的「現在判不了」會是 503 authorization_unavailable,那個才該重試 |
client_not_third_party |
這個 client 不是第三方類別(是第一方或內部工具) | 平台端問題;第三方不該拿到這種 client |
profile_not_supported |
token 的 profile 不在 v1 範圍——delegated 與 shared 落在這裡 |
改用本人(self)或機器(workload)token;代理要等 v2 |
subject_revoked |
service account 或使用者 session 已被撤銷/停用 | tenant 管理員重新啟用,或請使用者重新登入 |
epoch_changed |
token 的 actor_epoch 與帳號現值不符——帳號被撤權過 |
重新取一張 token |
capability_not_granted |
tenant 沒把這項能力授權給這個 app | tenant 管理員在後台加授權 |
plan_capability_excluded |
租戶方案不含這項能力 | 升級方案 |
capability_not_in_token |
能力有被授權,但這張 token 沒帶這個 scope | 換一張帶足 scope 的 token |
capability_unavailable |
這項能力在本部署尚未開放(目錄狀態不是可呼叫) | 看文件的可用狀態,等它上線 |
resource_type_mismatch |
能力宣告的資源型別與你打的資源對不上 | 修正呼叫 |
tenant_mismatch |
資源不屬於這張 token 的租戶 | 修正呼叫 |
no_relationship |
租戶對這個人沒有有效關係 | 修正呼叫,或先建立關係 |
forbidden |
兜底:Amygdala 回了本版 Gateway 不認識的 deny 代碼。仍然是拒絕,不會變成放行,也不會變成可重試的 503 | 回報並附上 x-request-id |
⚠️ tenant_mismatch 與 no_relationship 打在 person 資源上時會變成 404,
不是 403——否則 403 與 404 的差別本身就是一支「這個 person 存不存在」的
探測器(ADR-004 D9)。不透露資源是否存在是刻意的。
ℹ️ tenant_suspended 與 tenant_not_enabled 都不折成 404,即使打在
person 資源上也一樣回 403。它們講的是你的租戶(停權/第三方整合沒有生效),
不是目標資源存不存在,所以據此推不出任何關於那個 person 的事——
沒有要遮蔽的東西。反過來折成 404 會讓一個只是沒開整合的租戶
以為自己的人都不見了。
範例 missingCapability
{
"error": "capability_not_granted",
"message": "this application is not granted lightup.person.metadata.write",
"requestId": "req_01j8m4k2r7e9v3xq5w8n0tzh3k"
}
範例 planTooLow
{
"error": "plan_capability_excluded",
"message": "the tenant plan does not include this capability",
"requestId": "req_01j8m4k2r7e9v3xq5w8n0tzh4m"
}
NotFound
404 — 資源不存在,或存在但呼叫端連它存不存在都不該知道。 兩者刻意回同一個答案(ADR-004 D9)。
範例 default
{
"error": "not_found",
"message": "resource not found",
"requestId": "req_01j8m4k2r7e9v3xq5w8n0tzh5n"
}
Conflict
409 — 你和別人撞上了。沒有任何東西被寫入。 兩種:
revision_conflict— 送出的If-Match與現行ETag不符(有人搶先寫了)。 重新 GET、合併、帶新的ETag重送。already_exists— 送了If-None-Match: *要建立,但它已經存在。 改成 GET 讀出現行ETag,再用If-Match更新。
本 API 用 409 表達所有衝突,不用 412。 RFC 9110 對失敗的前置條件
給的是 412;收斂成單一狀態碼讓 client 只要分辨 Problem.error 就夠。
「前置條件標頭根本沒帶或帶重複」不是衝突,是 428,見下。
範例 conflict
{
"error": "revision_conflict",
"message": "the resource was modified; re-read and retry",
"requestId": "req_01j8m4k2r7e9v3xq5w8n0tzh6p"
}
範例 alreadyExists
{
"error": "already_exists",
"message": "the extension already exists; read its ETag and use If-Match",
"requestId": "req_01j8m4k2r7e9v3xq5w8n0tzh7q"
}
PreconditionRequired
428 — 這個寫入沒有表明它的前置條件(RFC 6585 §3)。
PUT 必須恰好帶一個:If-Match: "<etag>"(更新)或
If-None-Match: *(建立)。DELETE 必須帶 If-Match。
兩個都沒帶、或 PUT 同時帶兩個,就是這個錯誤。
沒有任何東西被寫入,而且重試同樣的請求永遠是同樣的結果—— 這是 client 的 bug,不是暫時狀況。本 API 沒有無條件覆寫的操作: 那正是遺失更新的來源(計畫 §6)。
範例 missing — 兩個都沒帶
{
"error": "precondition_required",
"message": "provide exactly one of If-Match or If-None-Match",
"requestId": "req_01j8m4k2r7e9v3xq5w8n0tzh7q"
}
範例 both — 兩個都帶
{
"error": "precondition_required",
"message": "If-Match and If-None-Match are mutually exclusive",
"requestId": "req_01j8m4k2r7e9v3xq5w8n0tzh8r"
}
PayloadTooLarge
413 — 單筆 data 超過 16 KiB。縮小內容,或把大東西放在你自己的資料庫
(計畫 §6:平台 metadata 不存照片與無界列表)。
範例 default
{
"error": "payload_too_large",
"message": "extension data exceeds 16 KiB",
"requestId": "req_01j8m4k2r7e9v3xq5w8n0tzh8r"
}
UnprocessableEntity
422 — 請求格式對,但內容不可接受:額度用盡、參數超界、schema 不符。
額度用盡不會刪任何資料。 既有資料照常可讀、可刪、可匯出。
範例 quota
{
"error": "quota_exceeded",
"message": "tenant reached 50000 records for this extension",
"requestId": "req_01j8m4k2r7e9v3xq5w8n0tzh9s"
}
範例 schema
{
"error": "schema_invalid",
"message": "data does not match the registered extension schema",
"requestId": "req_01j8m4k2r7e9v3xq5w8n0tzj1t"
}
TooManyRequests
429 — 限流。限流有兩層:tenant 與 service account/使用者 (計畫 §7)。兩層都可能觸發,回應不會告訴你是哪一層。
看 Retry-After 再重試。合法的大量同步不會被丟棄,會被要求放慢
——需要更高額度請升級方案,別用更多帳號繞過(那會在 tenant 層再撞一次)。
範例 default
{
"error": "rate_limited",
"message": "too many requests",
"requestId": "req_01j8m4k2r7e9v3xq5w8n0tzj2u"
}
AuthorizationUnavailable
503 — 平台現在無法判斷你有沒有權限。兩種,分開是因為要修的地方不同:
error |
什麼做不完 |
|---|---|
authorization_unavailable |
拿不到授權決定——Amygdala 不可用、逾時,或下游資料面不可用 |
token_verification_unavailable |
驗簽就做不完——JWKS 取不到,或 unknown kid 的有界重取失敗 |
兩者都不是拒絕。平台 fail-closed:判不了就不放行,而不是降級成只驗簽
(計畫 §5)。都可以重試,請用指數退避;Retry-After 是建議不是承諾。
403 和 503 永遠不會長得一樣:前者是「不准」,後者是「現在不知道」。
範例 default
{
"error": "authorization_unavailable",
"message": "authorization service temporarily unavailable; retry",
"requestId": "req_01j8m4k2r7e9v3xq5w8n0tzj3v"
}
OrderConflict
409 — 訂單操作與現況衝突。沒有任何東西被寫入或改變。 三種:
error |
意思 | 怎麼修 |
|---|---|---|
idempotency_key_reused |
同一個 Idempotency-Key 之前用在一份不同的建單請求上(下游代碼 IDEMPOTENCY_KEY_REUSED) |
換一個新的 key 建立另一筆訂單。同一筆意圖的重送要用同一個 key 與同一份請求 |
request_in_progress |
同一個 Idempotency-Key 的上一次請求還在處理中(下游代碼 IDEMPOTENCY_REQUEST_IN_PROGRESS)。回應帶 Retry-After: 2 |
等 Retry-After 秒後,用同一個 key、同一份請求重送 |
order_not_cancellable |
取消時訂單不可取消。detail 是下游代碼與訊息,例如 ORDER_ALREADY_CANCELLED、ORDER_NOT_CANCELLABLE、ORDER_CANCEL_PENDING_OPERATOR |
不要重試。讀 GET /v1/orders/{orderId} 確認現況 |
範例 idempotencyKeyReused
{
"error": "idempotency_key_reused",
"message": "this Idempotency-Key was used for a different request",
"requestId": "req_01j8m4k2r7e9v3xq5w8n0tzk4w"
}
範例 orderNotCancellable
{
"error": "order_not_cancellable",
"message": "the order cannot be cancelled in its current state",
"detail": "ORDER_ALREADY_CANCELLED: order is already cancelled",
"requestId": "req_01j8m4k2r7e9v3xq5w8n0tzl5x"
}
OrderUnprocessable
422 — 請求格式對,但內容不可接受。沒有任何東西被寫入。 兩種:
error |
意思 | 怎麼修 |
|---|---|---|
schema_invalid |
請求內容或標頭不符合該端點的 schema:未知欄位、必填缺漏、型別或範圍錯誤、格式不對的 id 或標頭(Idempotency-Key、X-LightUp-Operator、customerPersonId、expiresAt);也包括下游訂單服務回的 400(它沒有代碼) |
照 OpenAPI 的 schema 修正請求。不要原樣重送 |
product_unavailable |
訂單中有品項的 productId 在商品目錄裡不存在(下游代碼 ORD_019) |
確認 productId 來自目錄,不要自行拼裝 |
取消端點的 422 只會是 schema_invalid(reason 缺漏、超過 500 字元,或帶了未知欄位)。
範例 productUnavailable
{
"error": "product_unavailable",
"message": "a product in this order does not exist in the catalogue",
"requestId": "req_01j8m4k2r7e9v3xq5w8n0tzm6y"
}
TagConflict
409 — 標籤寫入與現況衝突。沒有任何東西被寫入。 三種新的代碼:
error |
意思 | 怎麼修 |
|---|---|---|
tag_writes_not_open |
這個租戶的客戶在這裡還不能寫標籤:租戶的身分切換尚未完成。這是狀態,不是權限 | 不要重試;等平台公告該租戶開放寫入 |
person_merged |
這位客戶已被合併到另一位,路徑上的 person id 不是正本 | 改用合併後的 person id(例如重新 POST /v1/persons:resolve)再送 |
tag_name_conflict |
建立標籤時,這個名稱在該分類下對應的標籤 id 已被一個後來改名或搬走的標籤占用 | 不要重試同一份請求;確認分類與名稱,或請租戶在後台整理該標籤 |
同一個 Idempotency-Key 用在不同的寫入上,也是 409,代碼是沿用的 idempotency_key_reused:
換一個新的 UUID 送另一個寫入;同一個寫入的重送要用同一個 key。
範例 tagWritesNotOpen
{
"error": "tag_writes_not_open",
"message": "tag writes are not open for this tenant yet",
"requestId": "req_01j8m4k2r7e9v3xq5w8n0tzn7z"
}
範例 personMerged
{
"error": "person_merged",
"message": "the person was merged into another person",
"requestId": "req_01j8m4k2r7e9v3xq5w8n0tzp8a"
}
TagUnprocessable
422 — 標籤請求格式對,但內容不可接受。沒有任何東西被寫入。 兩種新的代碼:
error |
意思 | 怎麼修 |
|---|---|---|
tag_limit_reached |
這位客戶帶著的標籤數已達上限 | 先移除不用的標籤,不要原樣重送 |
category_not_found |
建立標籤時指定的 categoryNodeId 不存在,或不是標籤分類 |
用 POST /v1/categories:lookup 取得分類 id;分類請由租戶在後台建立 |
請求本文、標頭或 id 不符合 schema 時仍是沿用的 schema_invalid(例如 Idempotency-Key 不是 UUID、
帶了未知欄位):照 OpenAPI 的 schema 修正請求,不要原樣重送。
範例 tagLimitReached
{
"error": "tag_limit_reached",
"message": "the person already holds the most tags allowed",
"requestId": "req_01j8m4k2r7e9v3xq5w8n0tzq9b"
}
範例 categoryNotFound
{
"error": "category_not_found",
"message": "the tag category does not exist",
"requestId": "req_01j8m4k2r7e9v3xq5w8n0tzr0c"
}
Schema
TokenRequest
application/x-www-form-urlencoded。三種 grant 各自需要的欄位不同, 所以用 oneOf 分開——送錯組合在 schema 層就看得出來,不必等伺服器回 400。
型別 —。
ClientCredentialsRequest
機器/背景。得到 workload token,沒有 refresh_token。 client_secret 可改放 Authorization: Basic;兩種擇一,不要同時送。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
grant_type |
string | 是 | |
client_id |
ClientId | 是 | |
client_secret |
string | 否 | service account 的機器憑證。用 client_secret_basic 時省略。 不要放進版本控制、前端 bundle 或 log。 |
scope |
ScopeString | 否 |
未列出的欄位不被接受(additionalProperties: false)。
AuthorizationCodeRequest
使用者授權完成後,用一次性 code 換 token。得到 self token。 PKCE 必填——第三方 public 與 confidential client 都要。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
grant_type |
string | 是 | |
client_id |
ClientId | 是 | |
client_secret |
string | 否 | confidential client 才有;public client 不送。 |
code |
string | 是 | /oauth2/authorize 導回時帶的一次性授權碼。用過就失效。 |
code_verifier |
string | 是 | PKCE verifier,43–128 字元。授權請求送的是它的 S256 雜湊 (code_challenge),plain 不支援。 最長 128 |
redirect_uri |
string | 是 | 必須與授權請求送出的那一個完全相同,且已登記在 client 上。 format uri |
未列出的欄位不被接受(additionalProperties: false)。
RefreshTokenRequest
續期使用者 token。嚴格 rotation:每次成功都會換一張新的 refresh token,舊的立即失效;重放已消耗的那一張會殺掉整個 family (第三方不適用任何放寬,見 ADR-004 D1)。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
grant_type |
string | 是 | |
client_id |
ClientId | 是 | |
client_secret |
string | 否 | confidential client 才有。 |
refresh_token |
string | 是 | 上一次回應給的那一張。不透明字串,不要解析。 |
scope |
— | 否 | 可選,只能縮小原本的 scope,不能放大。省略就沿用原本的。 |
未列出的欄位不被接受(additionalProperties: false)。
ClientId
第三方 client id,形狀 tp_<tenant label>_<slug>,由 amygdala 配發。
型別 string。pattern ^tp_[a-z0-9]+(?:-[a-z0-9]+)*_[a-z0-9]+(?:-[a-z0-9]+)*$
ScopeString
以空白分隔的能力清單(OAuth 慣例,不是逗號)。 實際拿到的 scope 是各層交集後的結果,可能比請求的少—— 以回應的 scope 欄位為準,不要假設拿到的就是送出去的。
型別 string。
TokenResponse
RFC 6749 §5.1 的 token 回應。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
access_token |
string | 是 | profile v2 access token(JWS,header typ: at+jwt、alg: ES256)。 當成不透明字串使用:要知道自己是誰請呼叫 GET /v1/me, 不要在 client 自行解析 claims 做授權判斷。 |
token_type |
string | 是 | 一律 Bearer。放進 Authorization: Bearer <access_token>。 |
expires_in |
integer | 是 | 剩餘秒數。v1 是 900(15 分)。不要寫死這個數字—— 照回應的值算到期時間。 |
scope |
— | 是 | 實際生效的能力,已是請求 ∩ grant ∩ 方案上限的結果。 可能少於你請求的;以這裡為準。 |
refresh_token |
string | 否 | 只有 authorization_code 與 refresh_token 會回。 client_credentials 不回——機器到期直接再換一張。 每次續期都會換新的,舊的立即失效。 |
未列出的欄位不被接受(additionalProperties: false)。
TokenError
RFC 6749 §5.2 的錯誤形狀。與本 API 其他端點的 Problem 不同—— 那是 OAuth 的既有契約,刻意保持原樣,不要把兩者混在同一個解析路徑。 /oauth2/revoke 與 /oauth2/introspect 的錯誤形狀相同但代碼集合不同, 用 OauthEndpointError——token 端點的 error 仍是這裡的四個封閉代碼。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
error |
string | 是 | 列舉:invalid_client、invalid_grant、invalid_scope、unsupported_grant_type |
error_description |
string | 否 | 一般是給人看的說明,字串隨時可能改;程式判斷請用 error。 唯一的例外是契約明文列出的機器可讀值,目前只有一個: invalid_grant + error_description: tenant_suspended(租戶被停權, 簽發端拒絕發 token)。其他值不保證穩定。 |
message |
string | 否 | 平台既有錯誤 body 的人類可讀欄位,實際回應會帶。 不是契約的一部分,字串與是否出現都可能改,不要解析它。 |
未列出的欄位不被接受(additionalProperties: false)。
OauthEndpointError
/oauth2/revoke 與 /oauth2/introspect 的錯誤形狀(同 RFC 6749 §5.2 的 error 形狀,不是 Problem)。代碼集合與 token 端點的 TokenError 不同, 所以另立一個 schema:不要把三者放進同一個解析路徑。 ℹ️ 來源與狀態:/oauth2/introspect 由 lightup-rs #1412 新增; /oauth2/revoke 是既有端點(discovery 公告為 revocation_endpoint), auth.lightup.tech 上的轉發同樣由 #1412 補上。#1412 已合併,amygdala 端自 amygdala-rs/v2.101.4 起在正式環境。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
error |
string | 是 | 列舉:invalid_request、invalid_client、bad_request、slow_down、temporarily_unavailable、not_found |
error_description |
string | 否 | 給人看的說明,字串隨時可能改;程式判斷請用 error。 |
message |
string | 否 | 平台既有錯誤 body 的人類可讀欄位。不是契約的一部分,不要解析它。 |
未列出的欄位不被接受(additionalProperties: false)。
IntrospectionResponse
RFC 7662 的 introspection 回應。非 active 時只有 active: false, 不分原因(不存在、過期、已消耗、別人的、背後 session 已結束都長一樣)。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
active |
boolean | 是 | 這張 token 現在是否有效。false 時其他欄位都不會出現。 |
sub |
string | 否 | 使用者的 psn_…(token 的 subject)。 |
sid |
string | 否 | OIDC session id;與 ID token 和 logout token 的 sid 相同。 32 個小寫十六進位字元(SHA-256 截斷),不是 UUID——不要拿它去 parse 成 UUID。 pattern ^[0-9a-f]{32}$ |
client_id |
string | 否 | 一定等於呼叫端自己的 client id——查不到別人的 token。 |
token_type |
string | 否 | 這張 token 是哪一種。access token 回 Bearer(RFC 6749 的 token type, 不是字串 access_token),refresh token 回 refresh_token。 列舉:Bearer、refresh_token |
exp |
integer | 否 | 到期時間(Unix 秒)。 |
iat |
integer | 否 | 簽發時間(Unix 秒)。 |
auth_time |
integer | 否 | 使用者當初登入的時間(Unix 秒),不是這次 refresh 的時間。 |
acr |
string | 否 | 當初登入的 authentication context class。目前只有兩個值: urn:lightup:loa:1(一般登入)與 urn:lightup:loa:2(做過 step-up)。 列舉:urn:lightup:loa:1、urn:lightup:loa:2 |
tenant_id |
string | 否 | 這張 token 所屬租戶。 |
scope |
string | 否 | 空白分隔的有效 scope;為空時這個欄位不出現。 |
未列出的欄位不被接受(additionalProperties: false)。
Problem
所有錯誤共用的形狀(RFC 9457 的精神,欄位刻意極簡)。 error 是穩定代碼,程式判斷請用它;message 是給人看的,隨時可能改字。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
error |
string | 是 | 穩定的機器可讀代碼。 列舉:invalid_token、client_unknown、client_disabled、actor_unknown、tenant_suspended、tenant_not_enabled、client_not_third_party、profile_not_supported、subject_revoked、epoch_changed、capability_not_granted、plan_capability_excluded、capability_not_in_token、capability_unavailable、resource_type_mismatch、tenant_mismatch、no_relationship、forbidden、not_found、revision_conflict、already_exists、precondition_required、payload_too_large、quota_exceeded、schema_invalid、rate_limited、idempotency_key_reused、request_in_progress、order_not_cancellable、product_unavailable、tag_writes_not_open、person_merged、tag_name_conflict、tag_limit_reached、category_not_found、authorization_unavailable、token_verification_unavailable |
message |
string | 否 | 人類可讀說明。不含資源是否存在的線索、內部路徑或任何秘密。 |
requestId |
string | 是 | 同 x-request-id。回報問題請附上。 |
detail |
string | 否 | 選填。目前只有 order_not_cancellable 使用,格式 "{code}: {message}",代碼與訊息來自下游 訂單服務。它不是 message 的同義詞;判斷請用 error。 |
未列出的欄位不被接受(additionalProperties: false)。
PersonTypeId
型別 string。pattern ^psn_[0-9a-hjkmnp-tv-z]{26}$
TenantTypeId
型別 string。pattern ^ten_[0-9a-hjkmnp-tv-z]{26}$
ExtensionId
型別 string。pattern ^[a-z][a-z0-9_]{2,63}$
Capability
能力 id。完整清單是版本化的能力目錄(crates/lightup-types/capabilities.toml), 對外由文件網站發布,每項標明說明、資源型別、最低方案等級與可用狀態 (planned / preview / ga)。v1 的五項是 ga(2026-10-05 起); order.create、order.read、order.cancel 是 preview(2026-10-17 起); tag.read、person.resolve、line.target、line.message_group.read 是 preview(2026-10-19 起); person.profile.read 是 preview(2026-10-25 起); tag.write、tag.define 2026-10-19 起為 planned,2026-10-26 起為 preview; person.wards.read 是 preview(2026-10-28 起)。目前沒有公開的 planned 項目。
型別 string。pattern ^lightup\.[a-z][a-z0-9.]*$
Me
這張 token 代表誰。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
subjectType |
string | 是 | 列舉:person、service_account |
subjectId |
string | 是 | psn_…(person)或 acc_…(service account,kind=service)。 |
tenantId |
TenantTypeId | 是 | |
clientId |
string | 是 | 第三方 client id,形狀 tp_<tenant label>_<slug>,全域唯一。 pattern ^tp_[a-z0-9]+(?:-[a-z0-9]+)*_[a-z0-9]+(?:-[a-z0-9]+)*$ |
scopes |
array<Capability> | 是 | 這張 token 實際生效的能力(已經是各層交集後的結果)。 |
actor |
object | 是 | 實際執行操作的帳號。 |
actor.accountId |
string | 是 | acc_…。人與 service account 同一個前綴,靠 subjectType 區分。 |
未列出的欄位不被接受(additionalProperties: false)。
Tenant
租戶的公開識別欄位。只有「這是誰」,沒有「它現在怎麼樣」。 不含租戶設定、方案等級、聯絡人、網域設定、社群 provider、LDAP, 也不含營運狀態(見下)。additionalProperties: false—— 內部欄位(例如 amygdala 的 slug)不會出現在這裡。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
tenantId |
TenantTypeId | 是 | |
displayName |
string | 是 |
未列出的欄位不被接受(additionalProperties: false)。
Person
最少欄位。要更多欄位是新的能力與新的 grant,不是在這裡加參數。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
personId |
PersonTypeId | 是 | |
displayName |
string | 是 | 顯示名稱。不保證唯一,也不是身分證明。 可能是空字串:這個人存在,只是平台上沒有任何可用的名字(尚未填、或只有 空白字元)。空字串不代表查不到這個人——查不到是 404——所以請不要把它當成 錯誤處理,要顯示的話自己用 personId 或你自己的資料補。 |
createdAt |
string | 是 | 這個人在平台上的建立時間。 format date-time |
未列出的欄位不被接受(additionalProperties: false)。
PersonExtensionWrite
寫入內容。data 整筆取代。 不要放照片、逐題事件、無界列表,或任何被當成權限/餘額/權益/身份綁定的欄位。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
schemaVersion |
integer | 是 | 必須是這個 extension 登記過的版本之一。 最小 1 |
data |
object | 是 | 序列化後 ≤ 16 KiB,超過回 413。 |
未列出的欄位不被接受(additionalProperties: false)。
PersonExtension
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
extensionId |
ExtensionId | 是 | |
personId |
PersonTypeId | 是 | |
schemaVersion |
integer | 是 | 最小 1 |
etag |
string | 是 | 同回應的 ETag 標頭。寫入時原封不動放進 If-Match。 |
data |
object | 是 | |
createdAt |
string | 是 | format date-time |
updatedAt |
string | 是 | format date-time |
updatedBy |
string | 是 | 最後寫入的 client id(不是使用者)。 要追到人,用 x-request-id 查稽核紀錄。 |
未列出的欄位不被接受(additionalProperties: false)。
PersonExtensionSummary
列表用的摘要,不含 data。要內容請用 key lookup 逐筆取。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
extensionId |
ExtensionId | 是 | |
schemaVersion |
integer | 是 | 最小 1 |
etag |
string | 是 | |
updatedAt |
string | 是 | format date-time |
updatedBy |
string | 是 |
未列出的欄位不被接受(additionalProperties: false)。
PersonExtensionPage
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
items |
array<PersonExtensionSummary> | 是 | 最多 100 筆 |
nextCursor |
string | null | 是 | 還有下一頁時是不透明字串;沒有下一頁時是 null。不要解析它。 |
未列出的欄位不被接受(additionalProperties: false)。
OrderCreateRequest
POST /v1/orders 的請求本文。未知欄位一律 422 schema_invalid。 沒有單價欄位:價格永遠由商品目錄決定,呼叫端無法指定。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
customerPersonId |
PersonTypeId | 是 | 買家(psn_ TypeID)。Gateway 把它換成下游訂單服務的客戶 id(同一個 UUID,不是另一套 id)。 |
items |
array<OrderLineRequest> | 是 | 最多 50 筆 |
remark |
string | 否 | 選填備註。 最長 1000 |
expiresAt |
string | 否 | 選填付款期限(RFC 3339)。有給的話必須晚於現在、且不超過現在起 10 年,否則 422 schema_invalid。 沒給的話,訂單在 30 分鐘後自動取消。 format date-time |
未列出的欄位不被接受(additionalProperties: false)。
OrderLineRequest
訂單的一個品項。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
productId |
string | 是 | 商品目錄的 id。只使用平台給過你的值。 最長 128 |
quantity |
integer | 是 | 最小 1;最大 999 |
attributes |
object | 否 | 選填,品項的附加屬性(字串對字串,最多 20 組)。 |
未列出的欄位不被接受(additionalProperties: false)。
OrderCancelRequest
POST /v1/orders/{orderId}/cancel 的請求本文。未知欄位一律 422 schema_invalid。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
reason |
string | 是 | 取消原因。 最長 500 |
未列出的欄位不被接受(additionalProperties: false)。
Order
訂單的對外投影(lightup.order.read)。只有這些欄位。 下游訂單服務的其他欄位 (建立方式、付款細節、買家內部 id、品項的 sku/名稱與屬性定義)一律不出現。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
orderId |
string | 是 | 訂單 id。之後的讀取與取消用它。 最長 128 |
orderNumber |
string | 是 | 訂單編號,已是給人看的格式。 |
status |
string | 是 | 訂單狀態,例如 PENDING。 |
paymentStatus |
string | 是 | 付款狀態,例如 UNPAID。 |
total |
number | 是 | 訂單總額。 |
netPaidTotal |
number | 是 | 淨已付金額;未付款時為 0。 |
expiresAt |
string | null | 是 | 付款期限(RFC 3339);訂單沒有期限時為 null。 format date-time |
createdAt |
string | 是 | 建立時間(RFC 3339)。 format date-time |
items |
array<OrderItem> | 是 |
未列出的欄位不被接受(additionalProperties: false)。
OrderItem
訂單的一個品項(對外投影)。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
productId |
string | 是 | 商品目錄的 id。 |
quantity |
integer | 是 | 數量。 |
unitPrice |
number | 是 | 單價(取自商品目錄)。 |
lineTotal |
number | 是 | 此品項的小計。 |
未列出的欄位不被接受(additionalProperties: false)。
TagId
標籤 id。只使用平台給過你的值,不要自行拼裝。
型別 string。pattern ^[A-Za-z0-9._-]{1,64}$;最長 64
CategoryNodeId
標籤分類的 id,來自 POST /v1/categories:lookup。1–128 個可見 ASCII 字元。
型別 string。pattern ^[!-~]{1,128}$;最長 128
LookupName
要查的名稱,1–200 字元。
型別 string。最長 200
PersonIdsRequest
POST /v1/persons:tags 與 POST /v1/line-targets 的請求本文。未知欄位一律 422 schema_invalid。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
personIds |
array<PersonTypeId> | 是 | 1–100 個 psn_ TypeID。有一個不合格,整個請求就是 422 schema_invalid。 最多 100 筆 |
未列出的欄位不被接受(additionalProperties: false)。
PersonIdsBatchRequest
POST /v1/tags/{tagId}/members:remove 的請求本文。未知欄位一律 422 schema_invalid。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
personIds |
array<PersonTypeId> | 是 | 1–1000 個 psn_ TypeID。有一個不合格,整個請求就是 422 schema_invalid。 最多 1000 筆 |
未列出的欄位不被接受(additionalProperties: false)。
TagMembersAddRequest
POST /v1/tags/{tagId}/members:add 的請求本文。未知欄位一律 422 schema_invalid。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
personIds |
array<PersonTypeId> | 是 | 1–1000 個 psn_ TypeID。有一個不合格,整個請求就是 422 schema_invalid。 最多 1000 筆 |
provenance |
string | 否 | 選填。產生這批成員的來源參照(例如規則 id、匯入批次 id),平台不解讀它。 pattern ^[A-Za-z0-9._:-]{1,128}$;最長 128 |
未列出的欄位不被接受(additionalProperties: false)。
TagMember
帶著這個標籤的一位客戶。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
personId |
PersonTypeId | 是 | |
addedAt |
string | 是 | 加上這個標籤的時間(RFC 3339)。 format date-time |
未列出的欄位不被接受(additionalProperties: false)。
TagMembersPage
GET /v1/tags/{tagId}/members 的一頁,依 person id 排序。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
members |
array<TagMember> | 是 | |
next |
PersonTypeId | 否 | 下一頁的 after;最後一頁沒有這個欄位。 |
未列出的欄位不被接受(additionalProperties: false)。
HeldTag
一位客戶帶著的一個標籤。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
tagId |
TagId | 是 | |
addedAt |
string | 是 | 加上這個標籤的時間(RFC 3339)。 format date-time |
未列出的欄位不被接受(additionalProperties: false)。
PersonTags
一位客戶與他帶著的標籤。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
personId |
PersonTypeId | 是 | |
tags |
array<HeldTag> | 是 |
未列出的欄位不被接受(additionalProperties: false)。
PersonsTagsResponse
POST /v1/persons:tags 的回應。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
persons |
array<PersonTags> | 是 |
未列出的欄位不被接受(additionalProperties: false)。
LookupOutcome
名稱查詢的結果,封閉集合:FOUND(剛好一個)、NOT_FOUND(沒有)、AMBIGUOUS(不只一個)。
型別 string。列舉:FOUND、NOT_FOUND、AMBIGUOUS
TagLookupRequest
POST /v1/tags:lookup 的請求本文。未知欄位一律 422 schema_invalid。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
names |
array<LookupName> | 是 | 最多 100 筆 |
categoryNodeId |
CategoryNodeId | 否 | 選填。只在這一個標籤分類下找。 |
未列出的欄位不被接受(additionalProperties: false)。
TagLookupResult
一個名稱的查詢結果。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
name |
string | 是 | 請求裡的那個名稱。 |
outcome |
LookupOutcome | 是 | |
tagId |
TagId | 否 | 只有 FOUND 時出現。 |
未列出的欄位不被接受(additionalProperties: false)。
TagLookupResponse
POST /v1/tags:lookup 的回應。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
results |
array<TagLookupResult> | 是 |
未列出的欄位不被接受(additionalProperties: false)。
CategoryLookupRequest
POST /v1/categories:lookup 的請求本文。未知欄位一律 422 schema_invalid。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
names |
array<LookupName> | 是 | 最多 100 筆 |
未列出的欄位不被接受(additionalProperties: false)。
CategoryLookupResult
一個分類名稱的查詢結果。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
name |
string | 是 | 請求裡的那個名稱。 |
outcome |
LookupOutcome | 是 | |
categoryNodeId |
CategoryNodeId | 否 | 只有 FOUND 時出現。 |
candidates |
array<CategoryNodeId> | 否 | 只有 AMBIGUOUS 時出現:每一個叫這個名稱的分類 id。 |
未列出的欄位不被接受(additionalProperties: false)。
CategoryLookupResponse
POST /v1/categories:lookup 的回應。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
results |
array<CategoryLookupResult> | 是 |
未列出的欄位不被接受(additionalProperties: false)。
PersonResolveRequest
POST /v1/persons:resolve 的請求本文。未知欄位一律 422 schema_invalid。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
legacyIds |
array | 是 | 1–500 個舊客戶 id,每個 1–128 字元。 最多 500 筆 |
未列出的欄位不被接受(additionalProperties: false)。
ResolvedLegacyId
一個舊客戶 id 的對應結果。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
legacyId |
string | 是 | 請求裡的那個舊 id。 |
outcome |
string | 是 | 封閉集合,見 POST /v1/persons:resolve 的說明。 列舉:RESOLVED、NOT_FOUND、AMBIGUOUS、INVALID |
personId |
PersonTypeId | 否 | 只有 RESOLVED 時出現。 |
未列出的欄位不被接受(additionalProperties: false)。
PersonResolveResponse
POST /v1/persons:resolve 的回應。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
results |
array<ResolvedLegacyId> | 是 |
未列出的欄位不被接受(additionalProperties: false)。
PersonProfilesRequest
POST /v1/persons:profiles 的請求本文。未知欄位一律 422 schema_invalid。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
ids |
array | 是 | 1–500 個 id,每個 1–128 字元:裸的舊客戶 UUID 或 psn_ person id, 分辨方式與 POST /v1/persons:resolve 相同。沒有列表形式:要讀的每一位都要指名。 最多 500 筆 |
未列出的欄位不被接受(additionalProperties: false)。
PersonProfile
一個 id 的基本資料結果。只有 FOUND 時帶 personId 與五個基本資料欄位, 而且五個欄位一定出現、沒有值時是 null;其他結果只有 id 與 outcome。 不含電話、email 或地址。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
id |
string | 是 | 請求裡的那個 id,原樣回傳。 |
outcome |
string | 是 | 封閉集合,見 POST /v1/persons:profiles 的說明。 列舉:FOUND、NOT_FOUND、AMBIGUOUS、INVALID |
personId |
PersonTypeId | 否 | 只有 FOUND 時出現。 |
givenName |
string | null | 否 | 名字。只有 FOUND 時出現;沒有值時是 null。 最長 200 |
familyName |
string | null | 否 | 姓氏。只有 FOUND 時出現;沒有值時是 null。 最長 200 |
displayName |
string | null | 否 | 顯示名稱。只有 FOUND 時出現;沒有值時是 null。新系統建立的孩子常常只有這一個名稱, givenName、familyName 都是 null 時請改用它。 最長 200 |
birthDate |
string | null | 否 | 生日,YYYY-MM-DD。只有 FOUND 時出現;沒有值或不是真實日期時是 null。 pattern ^\d{4}-\d{2}-\d{2}$;format date |
gender |
string | null | 否 | 性別,封閉集合。只有 FOUND 時出現;沒有值或不在集合內時是 null。 列舉:male、female、other、unknown、null |
未列出的欄位不被接受(additionalProperties: false)。
PersonProfilesResponse
POST /v1/persons:profiles 的回應。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
profiles |
array<PersonProfile> | 是 |
未列出的欄位不被接受(additionalProperties: false)。
PersonWard
一個孩子。personId 與五個基本資料欄位一定出現,沒有值時是 null, 規則與 POST /v1/persons:profiles 的 FOUND 結果相同。不含電話、email 或地址。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
personId |
PersonTypeId | 是 | |
givenName |
string | null | 是 | 名字;沒有值時是 null。 最長 200 |
familyName |
string | null | 是 | 姓氏;沒有值時是 null。 最長 200 |
displayName |
string | null | 是 | 顯示名稱;沒有值時是 null。新系統建立的孩子常常只有這一個名稱, givenName、familyName 都是 null 時請改用它。 最長 200 |
birthDate |
string | null | 是 | 生日,YYYY-MM-DD;沒有值或不是真實日期時是 null。 pattern ^\d{4}-\d{2}-\d{2}$;format date |
gender |
string | null | 是 | 性別,封閉集合;沒有值或不在集合內時是 null。 列舉:male、female、other、unknown、null |
未列出的欄位不被接受(additionalProperties: false)。
AnalyticsAnswer
一個報表指標。都是彙總數字,不含個人資料。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
meta |
object | 是 | |
meta.topic |
string | 是 | |
meta.metric |
string | 是 | |
meta.granularity |
string | 是 | |
meta.timezone |
string | 是 | |
meta.currency |
string | 是 | |
meta.rangeStart |
string | 是 | 範圍起點(含),租戶時區的日期。 |
meta.rangeEnd |
string | 是 | 範圍終點(不含),租戶時區的日期。 |
meta.compareStart |
string | 否 | |
meta.compareEnd |
string | 否 | |
meta.isPartial |
boolean | 是 | true 表示有部分資料讀取失敗,數字可能偏低。 |
meta.generatedAt |
string | 是 | |
meta.notes |
array | 是 | 這批數字的限制,請一併讀取。 |
schema |
array | 是 | rows 裡每個 key 的定義。 |
rows |
array | 是 | |
series |
array | 是 |
未列出的欄位不被接受(additionalProperties: false)。
AnalyticsMetricList
這個報表領域開放的指標。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
metrics |
array | 是 |
未列出的欄位不被接受(additionalProperties: false)。
PersonWardsResponse
GET /v1/persons/{personId}/wards 的回應。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
guardian |
object | 是 | 平台找到的監護人。 |
guardian.personId |
PersonTypeId | 是 | |
wards |
array<PersonWard> | 是 | 目前生效中的監護關係裡的孩子,最多 50 個。沒有孩子時是空陣列。 最多 50 筆 |
truncated |
boolean | 是 | 孩子超過 50 個、只回了前 50 個時是 true。 |
未列出的欄位不被接受(additionalProperties: false)。
LineTarget
一位客戶的 LINE 投遞結果。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
personId |
PersonTypeId | 是 | |
outcome |
string | 是 | 封閉集合,見 POST /v1/line-targets 的說明。 列舉:DELIVERABLE、NO_LINE、NOT_FOUND、AMBIGUOUS、BLOCKED、UNSUBSCRIBED |
lineUserId |
string | 否 | 只有 DELIVERABLE 時出現。 這位客戶在該租戶自己的 LINE 官方帳號下的 LINE user id; 只能用那一個官方帳號送訊息,換到別的官方帳號沒有意義。 |
未列出的欄位不被接受(additionalProperties: false)。
LineTargetsResponse
POST /v1/line-targets 的回應。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
targets |
array<LineTarget> | 是 |
未列出的欄位不被接受(additionalProperties: false)。
TagMembershipChange
單一成員寫入(PUT/DELETE /v1/persons/{personId}/tags/{tagId})的結果。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
changed |
boolean | 是 | 這次呼叫真的加上(或移除)了這個成員關係。 |
replayed |
boolean | 是 | 同一個 Idempotency-Key 之前已經套用過;這次沒有再寫入。 |
未列出的欄位不被接受(additionalProperties: false)。
SkippedPerson
批次寫入時被略過的一位客戶。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
personId |
PersonTypeId | 是 | |
reason |
string | 是 | 封閉集合:missing(租戶沒有這位客戶)、not_canonical(已被合併)、tag_limit(標籤數已達上限)。 列舉:missing、not_canonical、tag_limit |
未列出的欄位不被接受(additionalProperties: false)。
TagMembersBatchResult
批次成員寫入(members:add/members:remove)的結果。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
changed |
integer | 是 | 這次真的加上(或移除)的客戶數。 最小 0 |
unchanged |
integer | 是 | 本來就是要求的狀態、這次沒有改變的客戶數。 最小 0 |
skipped |
array<SkippedPerson> | 是 | 被略過的每一位客戶與原因。 |
replayed |
boolean | 是 | true:這批(或其中一部分)先前已用同一個 Idempotency-Key 套用過,這次沒有重做。 平台不保存第一次的回應,所以已套用的那部分不會再出現在 changed/unchanged/skipped 裡; 需要完整的略過名單,請以第一次收到的回應為準,或改用 POST /v1/persons:tags 查目前狀態。 |
未列出的欄位不被接受(additionalProperties: false)。
TagCreateRequest
POST /v1/tags 的請求本文。未知欄位一律 422 schema_invalid。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
tagName |
string | 是 | 標籤名稱。先去掉前後空白,再檢查 1–100 字元、不含控制字元。 最長 100 |
categoryNodeId |
CategoryNodeId | 是 | 一個已經存在的標籤分類。不存在 → 422 category_not_found。 |
backgroundColor |
string | 否 | 選填,#RRGGBB。 pattern ^#[0-9A-Fa-f]{6}$ |
description |
string | 否 | 選填,最多 500 字元(去掉前後空白後計算;為空視同沒給)。 最長 500 |
未列出的欄位不被接受(additionalProperties: false)。
TagCreated
POST /v1/tags 的回應。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
tagId |
TagId | 是 | |
created |
boolean | 是 | true = 這次建立(201);false = 這個分類下已有同名標籤,回傳的是它(200)。 |
未列出的欄位不被接受(additionalProperties: false)。
LineMessageGroupId
LINE 訊息組 id。只使用平台給過你的值,不要自行拼裝。
型別 string。pattern ^[A-Za-z0-9_-]{1,64}$;最長 64
LineMessage
訊息組裡的一則訊息(對外投影)。只有這些欄位。 | type | 帶什麼 | |---|---| | text | text | | image、video | originalContentId、previewImageId:媒體 id,不是網址 | | 其他(或 null) | 只有 type 與 complete: false | complete 為 false 時不要送出這個訊息組:表示這則訊息有平台沒有交給你的部分 (本版不認得的訊息類型,或多出來的欄位),照著送出去會和原本的內容不一樣。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
type |
string | null | 是 | 訊息類型,例如 text、image、video。存的訊息沒有類型時是 null。 |
complete |
boolean | 是 | 這則訊息的內容是否完整交給你了。false → 整個訊息組都不要送。 |
text |
string | 否 | 只有 type: text 時出現。訊息文字。 |
originalContentId |
string | 否 | 只有 type: image/video 時出現。原始媒體的 id(不是網址)。 |
previewImageId |
string | 否 | 只有 type: image/video 時出現。預覽圖的 id(不是網址)。 |
未列出的欄位不被接受(additionalProperties: false)。
LineMessageGroup
一個 LINE 訊息組(對外投影,lightup.line.message_group.read)。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
id |
LineMessageGroupId | 是 | |
name |
string | 是 | 訊息組名稱。 |
updatedAt |
string | 是 | 最後更新時間(RFC 3339,UTC,毫秒精度)。 format date-time |
messages |
array<LineMessage> | 是 | 依原本的順序。 |
未列出的欄位不被接受(additionalProperties: false)。
LineMessageGroupMatches
GET /v1/line-message-groups?name=… 的回應。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
name |
string | 是 | 比對用的名稱(去掉前後空白後)。 |
matched |
integer | 是 | 回來的訊息組數,等於 items 的長度。 最小 0;最大 10 |
truncated |
boolean | 是 | true = 符合的不只回來的這些(上限 10 個)。 |
items |
array<LineMessageGroup> | 是 | 名稱完全相同的訊息組,依 id 排序。 最多 10 筆 |
未列出的欄位不被接受(additionalProperties: false)。
安全機制
bearerAuth
LightUp profile-v2 access token。Authorization: Bearer <token>。
Gateway 驗這些,缺一不可:
- 簽章 ES256,key 取自固定 JWKS
https://auth.lightup.tech/.well-known/jwks.json iss是平台 issuer(不依 token 自報的iss去別處取 key)aud=lightup-api- JOSE header
typ=at+jwt→ ID token 在這裡就被擋掉 profile∈ {self,workload} — v1 只有這兩種;delegated與shared一律拒- 未過期
用錯 token(ID token、第一方 storefront token、內部 x-system-token)一律 401。
oauth2AuthorizationCode
使用者授權(互動式)。public client 強制 PKCE S256; 第三方 confidential client 也必填 PKCE(不吃第一方的相容路徑)。
發出的 token 是 profile v2 self——代表登入的本人,而且只有本人。
v1 不簽發代理(delegated)token,同意頁也沒有「選擇被代理對象」這一步。
refresh 走嚴格 rotation:重放已消耗的 refresh 會殺掉整個 family。
第三方不會拿到 reuse grace、sliding 或 absolute-max 放寬。
flow authorizationCode
- authorizationUrl:
https://auth.lightup.tech/oauth2/authorize - tokenUrl:
https://auth.lightup.tech/oauth2/token - refreshUrl:
https://auth.lightup.tech/oauth2/token
| scope | 說明 |
|---|---|
lightup.profile.self.read |
讀這張 token 代表的身分 |
lightup.person.read |
讀獲授權人員的最少欄位 |
lightup.person.metadata.read |
讀本 app 自己的人員 metadata |
lightup.person.metadata.write |
寫/刪本 app 自己的人員 metadata |
lightup.tenant.info.read |
讀租戶公開識別欄位 |
oauth2ClientCredentials
機器/背景操作。主體是 service account,不是 client:
client 憑證證明「哪支程式」,token 的 sub 是租戶的 service account
(acc_…,AccountKind::Service——與人使用同一個 id 前綴)。
發出的 token 是 profile v2 workload,TTL 15 分,沒有 refresh
(到期就重新換一張)。
實際 scope = 請求的 scope ∩ service account 的 grantedCapabilities
∩ 租戶方案上限。交集為空 → invalid_scope,不會發一張沒有 scope 的 token。
憑證輪替:建立 next secret → 兩把並存最長 7 天 → promote,舊的立即失效。 撤銷:停用帳號或推進 epoch,在途 token 在下一個請求即失效。
client_credentials 只在部署開啟第三方整合時才被 /oauth2/token 接受,
discovery 的 grant_types_supported 也只在那時公告它(ADR-004 D3)。
flow clientCredentials
- tokenUrl:
https://auth.lightup.tech/oauth2/token
| scope | 說明 |
|---|---|
lightup.profile.self.read |
讀這張 token 代表的 service account |
lightup.person.read |
讀獲授權人員的最少欄位 |
lightup.person.metadata.read |
讀本 app 自己的人員 metadata |
lightup.person.metadata.write |
寫/刪本 app 自己的人員 metadata |
lightup.tenant.info.read |
讀租戶公開識別欄位 |
lightup.order.create |
以目錄價格為租戶的客戶建立未付款訂單(僅機器流程) |
lightup.order.read |
讀取本 app 建立的訂單狀態、金額與付款狀態(僅機器流程) |
lightup.order.cancel |
取消本 app 建立的未付款訂單(僅機器流程) |
lightup.tag.read |
讀租戶的客戶帶著哪些標籤、帶著某標籤的客戶,並以名稱查標籤與標籤分類(僅機器流程) |
lightup.person.resolve |
把租戶的舊客戶 id 對應到 person id(僅機器流程) |
lightup.line.target |
讀租戶的客戶能不能用 LINE 聯絡;能的話,回傳他在該租戶自己的 LINE 官方帳號下的 LINE user id(僅機器流程) |
lightup.tag.write |
為客戶加上、移除租戶的標籤(僅機器流程) |
lightup.tag.define |
在租戶既有的標籤分類下建立標籤(僅機器流程) |
lightup.line.message_group.read |
以 id 或完整名稱讀取租戶的 LINE 訊息組:每則訊息的文字與媒體 id(僅機器流程) |
lightup.person.profile.read |
以 id 讀取租戶指名客戶的名字、姓氏、顯示名稱、生日與性別(僅機器流程) |
lightup.person.wards.read |
列出租戶的某位客戶目前監護中的孩子,附每個孩子的基本資料(僅機器流程) |
lightup.analytics.traffic.read |
讀取租戶的網站流量與結帳漏斗報表(彙總,僅機器流程) |