標籤與顧客(預覽)
狀態:預覽(
preview),2026-10-19 加入;兩項寫入能力 2026-10-26 由規劃(planned)轉為預覽。 這些能力的契約已定案、可以呼叫,但尚未適用正式版的支援與棄用保證:欄位、錯誤細節與行為在轉為ga之前仍可能調整,調整會照版本與棄用公告。標籤成員的寫入在租戶的身分切換完成之前一律被拒(409tag_writes_not_open),見下方「寫入」一節。2026-10-25 加入的客戶基本資料讀取(lightup.person.profile.read)同樣是預覽。2026-10-28 加入的客戶被監護人讀取(lightup.person.wards.read)同樣是預覽。
這組操作讓租戶自己的後台工具,以機器流程讀取租戶的標籤與客戶:誰帶著哪個標籤、以名稱找標籤與標籤分類、把舊客戶 id 對應到 person id、讀取指名客戶的基本資料(名字、生日與性別)、哪些客戶能用 LINE 聯絡,以及為客戶加上、移除標籤與建立標籤。
| 能力 | 狀態 | 操作 | 作用 |
|---|---|---|---|
lightup.tag.read |
預覽 | GET /v1/tags/{tagId}/members |
列出帶著某個標籤的客戶(分頁) |
lightup.tag.read |
預覽 | POST /v1/persons:tags |
讀取最多 100 位客戶各自帶著的標籤 |
lightup.tag.read |
預覽 | POST /v1/tags:lookup |
以名稱查標籤 id |
lightup.tag.read |
預覽 | POST /v1/categories:lookup |
以名稱查標籤分類 id |
lightup.person.resolve |
預覽 | POST /v1/persons:resolve |
把舊客戶 id 對應到 person id |
lightup.person.profile.read |
預覽 | POST /v1/persons:profiles |
以 id 讀取最多 500 位客戶的名字、姓氏、顯示名稱、生日與性別 |
lightup.person.wards.read |
預覽 | GET /v1/persons/{personId}/wards |
列出一位客戶目前監護中的孩子(最多 50 個)與他們的基本資料 |
lightup.line.target |
預覽 | POST /v1/line-targets |
讀取客戶能不能用 LINE 聯絡,以及他的 LINE user id |
lightup.tag.write |
預覽 | PUT/DELETE /v1/persons/{personId}/tags/{tagId} |
為一位客戶加上/移除一個標籤 |
lightup.tag.write |
預覽 | POST /v1/tags/{tagId}/members:add、:remove |
為最多 1000 位客戶加上/移除同一個標籤 |
lightup.tag.define |
預覽 | POST /v1/tags |
在既有的標籤分類下建立標籤 |
本 API 沒有建立或修改標籤分類、改標籤名稱、刪除標籤的操作;分類請由租戶在後台建立。
範圍與授權
- 只限機器流程。 呼叫者必須持有 service account 的 token(
client_credentials,workload,TTL 15 分,沒有 refresh)。使用者本人的 token 呼叫這些操作會得到 403profile_not_supported,與換不換 token 無關——換成機器流程才行。 - 方案等級 L2 起。 低於 L2 的租戶會得到 403
plan_capability_excluded。 - 資源是租戶,不是人員。 授權是租戶層級的:作用對象是租戶自己的標籤與客戶,不會因為某位客戶還沒有在平台的人員資料裡登記就整筆被拒。
- 只看得到自己的租戶。 每個操作都只作用在這張 token 的租戶上;別的租戶的標籤或客戶一律當成不存在。
- 租戶要先核准。 每一項能力都要由租戶管理員在後台核准給這支應用程式(見登記與憑證);沒核准的那一項會被拒(403
capability_not_granted)。 - 「開全部」是當下的快照。 租戶在 2026-10-19 之前核准的授權不會自動多出這幾項;要用到它們,租戶要重新核准。之後新記錄的授權(包括「開全部」)會包含三項預覽能力,當時不包含兩項寫入能力。兩項寫入能力 2026-10-26 轉為預覽:在帶著它們的發版之前記錄的授權(包括當時的「開全部」)不含它們,要用到它們,租戶要重新核准;之後新記錄的「開全部」會包含它們。
lightup.person.profile.read(2026-10-25 加入)也一樣:在帶著它的發版之前記錄的授權不含它,要用到它,租戶要重新核准;之後新記錄的「開全部」會包含它。
共同規則
- 本文是封閉的。 請求本文帶了契約沒有的欄位,一律 422
schema_invalid。 - 形狀先檢查。 本文、查詢參數與標頭不合格,在判權之前就回 422
schema_invalid;路徑上的 id 形狀不合(tagId不是 1–64 個[A-Za-z0-9._-],personId不是psn_TypeID),在判權之前就回 404。 - 一個壞 id 就整筆拒絕。 清單裡只要有一個
personId不是psn_TypeID,整個請求就是 422,不會只處理對的那幾個。 - 結果是封閉集合。 每個
outcome與reason都只會是下面表格列出的值。 - 標籤 id、分類 id 與 person id 只使用平台給你的值,不要自行拼裝。
列出帶著某個標籤的客戶:GET /v1/tags/{tagId}/members
GET https://api.lightup.tech/v1/tags/{tagId}/members?limit=100
Authorization: Bearer <workload token>
| 查詢參數 | 必填 | 說明 |
|---|---|---|
limit |
否 | 每頁筆數,1–100,省略時是 50 |
after |
否 | 上一頁回應的 next(一個 psn_ TypeID),原樣放回來取下一頁 |
只接受這兩個查詢參數:帶了未知或重複的參數、after 不是 psn_ TypeID、limit 不在 1–100,都是 422 schema_invalid,在判權之前就回。
{
"members": [
{ "personId": "psn_01j8m4k2r7e9v3xq5w8n0tza6b", "addedAt": "2026-10-19T09:30:00Z" }
],
"next": "psn_01j8m4k2r7e9v3xq5w8n0tza6b"
}
- 依 person id 排序。回應沒有
next就是最後一頁。 - 標籤不存在或不屬於這個租戶:404
not_found,不分辨。
讀取客戶帶著的標籤:POST /v1/persons:tags
{ "personIds": ["psn_01j8m4k2r7e9v3xq5w8n0tza6b"] }
personIds 是 1–100 個 psn_ TypeID。回應:
{
"persons": [
{
"personId": "psn_01j8m4k2r7e9v3xq5w8n0tza6b",
"tags": [{ "tagId": "0b5d6a3e-2f0c-4f39-9b1a-6f2d1c0e9a77", "addedAt": "2026-10-19T09:30:00Z" }]
}
]
}
以名稱查標籤與分類:POST /v1/tags:lookup、POST /v1/categories:lookup
{ "names": ["永和 週六"], "categoryNodeId": "node-7" }
names是 1–100 個名稱,每個 1–200 字元。categoryNodeId只有tags:lookup收,選填:只在那一個分類下找。它來自categories:lookup的回應。
每個名稱回一個結果:
outcome |
意思 | 帶什麼 |
|---|---|---|
FOUND |
剛好一個 | 標籤:tagId;分類:categoryNodeId |
NOT_FOUND |
沒有 | — |
AMBIGUOUS |
不只一個 | 分類:candidates(每一個叫這個名稱的分類 id)。標籤:帶 categoryNodeId 限定分類再查一次 |
AMBIGUOUS 時平台不替你選。 不要拿第一個來用。
把舊客戶 id 對應到 person id:POST /v1/persons:resolve
{ "legacyIds": ["5d7c0b0e-8a33-4b1c-9b0e-2f2f0b0e8a33"] }
legacyIds 是 1–500 個舊客戶 id,每個 1–128 字元。每個回一個結果:
outcome |
意思 | 怎麼做 |
|---|---|---|
RESOLVED |
對應到一位客戶,帶 personId |
之後一律用這個 personId |
NOT_FOUND |
這個租戶沒有這個舊 id 的對應 | 確認這個 id 是這個租戶的 |
AMBIGUOUS |
平台存的對應彼此不一致(例如對到兩位客戶) | 不要替它選邊,也不要對它發送行銷訊息;請洽租戶管理員 |
INVALID |
不是任何一種拼法的使用者 id 或 person id | 修正你送出的值 |
讀取客戶基本資料:POST /v1/persons:profiles
能力 lightup.person.profile.read,預覽,2026-10-25 加入。
{ "ids": ["5d7c0b0e-8a33-4b1c-9b0e-2f2f0b0e8a33", "psn_01j8m4k2r7e9v3xq5w8n0tza6c"] }
ids是 1–500 個 id,每個 1–128 字元。每個 id 可以是裸的舊客戶 UUID,也可以是psn_person id;平台分辨的方式與POST /v1/persons:resolve完全相同,兩種可以混在同一個請求裡。- 沒有列出全部客戶的形式。 要讀誰就要逐一指名,例如點名表上的那幾位孩子;一次最多 500 個,超過請分批。
- 本文是封閉的:多了別的欄位,或
ids的數量、長度不合,都是 422schema_invalid,在判權之前就回。
每個 id 回一個結果,id 是你送出的原值:
{
"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
},
{ "id": "00000000-0000-4000-8000-000000000000", "outcome": "NOT_FOUND" }
]
}
outcome |
意思 | 怎麼做 |
|---|---|---|
FOUND |
找到一位客戶,帶 personId 與五個基本資料欄位 |
照下面的欄位規則顯示 |
NOT_FOUND |
這個租戶沒有這個 id 的客戶 | 確認這個 id 是這個租戶的 |
AMBIGUOUS |
平台存的對應彼此不一致(例如對到兩位客戶) | 不要替它選邊;請洽租戶管理員 |
INVALID |
不是任何一種拼法的使用者 id 或 person id | 修正你送出的值 |
只有 FOUND 帶資料。 其他結果只有 id 與 outcome。FOUND 旁的五個欄位一定出現,沒有值時是 null:
| 欄位 | 內容 |
|---|---|
givenName |
名字 |
familyName |
姓氏 |
displayName |
顯示名稱 |
birthDate |
生日,YYYY-MM-DD |
gender |
性別,封閉集合:male、female、other、unknown |
- 新系統建立的孩子常常只有
displayName,名字與姓氏都是null。givenName與familyName都沒有值時,請改用displayName顯示;三個都是null時才當成沒有名字。 - 不合規則的值一律回
null,不會讓整批失敗。 性別不在上面的集合裡、生日不是真實存在的YYYY-MM-DD、名稱去掉前後空白後為空或超過 200 字元,都會以null回傳。回傳的名稱是去掉前後空白之後的值;生日必須剛好是YYYY-MM-DD的寫法(例如2019-4-07回null)。所以null代表「沒有可用的值」,不一定代表平台沒有存。 - 不回傳電話、email 或地址。 這個操作只有上面五個欄位。
- 平台每次呼叫都記一筆稽核紀錄(哪支應用程式、哪個帳號、指名了幾位、找到幾位)。
- 冪等:唯讀,可以安全重送。
列出客戶監護中的孩子:GET /v1/persons/{personId}/wards
能力 lightup.person.wards.read,預覽,2026-10-28 加入。
personId是監護人:psn_person id,或訂單customerId帶的裸 UUID(舊系統的拼法,指的是同一個人)。UUID 必須是帶連字號的8-4-4-4-12形式,大小寫皆可;其他形式(不帶連字號、加大括號、全零)在判權之前回 404。- 一次查一位監護人;沒有列出所有監護關係的形式。
{
"guardian": { "personId": "psn_01j8m4k2r7e9v3xq5w8n0tza6b" },
"wards": [
{
"personId": "psn_01j8m4k2r7e9v3xq5w8n0tza6c",
"givenName": "小明",
"familyName": "王",
"displayName": "王小明",
"birthDate": "2019-04-07",
"gender": "male"
}
],
"truncated": false
}
- 每個孩子的五個欄位與
POST /v1/persons:profiles的FOUND結果相同:一定出現,沒有值時是null,不合規則的值也一樣回null。名字與姓氏都是null時請改用displayName。 - 只列生效中的監護關係。 草稿(還沒生效)與已撤銷的關係不會出現。
- 最多 50 個孩子。 超過時只回前 50 個,
truncated是true;否則是false。 - 平台在這個租戶找不到這位監護人回 404;找到但沒有孩子回 200,
wards是空陣列。 - 不回傳電話、email 或地址,也不回傳監護關係本身的 id。
- 平台每次呼叫都記一筆稽核紀錄。
- 冪等:唯讀,可以安全重送。
LINE 投遞對象:POST /v1/line-targets
{ "personIds": ["psn_01j8m4k2r7e9v3xq5w8n0tza6b"] }
personIds 是 1–100 個 psn_ TypeID。回應:
{
"targets": [
{ "personId": "psn_01j8m4k2r7e9v3xq5w8n0tza6b", "outcome": "DELIVERABLE", "lineUserId": "U0123456789abcdef0123456789abcdef" }
]
}
lineUserId 是這位客戶在該租戶自己的 LINE 官方帳號下的 LINE user id。 這個值只能用該租戶自己的官方帳號送訊息給他;換到別的官方帳號沒有意義。它也是客戶的個人資料:只用在送訊息上,不要轉給別人。
outcome |
意思 | 怎麼做 |
|---|---|---|
DELIVERABLE |
可以送,帶 lineUserId |
用該租戶的官方帳號送給這個 lineUserId |
NO_LINE |
這位客戶沒有 LINE 身分 | 不要用 LINE 送 |
NOT_FOUND |
這個租戶沒有這個 id 的客戶 | 確認 personId 來自平台 |
AMBIGUOUS |
這位客戶有不只一個 LINE id,或彼此不一致 | 哪一個都不要送;平台不替你選 |
BLOCKED |
這位客戶已被封鎖(例如員工在聊天室封鎖) | 不要送 |
UNSUBSCRIBED |
這位客戶取消訂閱 | 不要送 |
- 只有
DELIVERABLE帶lineUserId;其他結果一律不帶。 - 結果反映當下的狀態。客戶隨時可能取消訂閱或被封鎖,送之前再問一次,不要長期快取。
寫入
租戶的身分切換完成之前,不要開始寫入標籤成員。 下面四個成員寫入(
PUT/DELETE /v1/persons/{personId}/tags/{tagId}、members:add、:remove)在租戶的身分切換完成之前一律回 409tag_writes_not_open:這是租戶的狀態,不是權限問題,重試、換 token 或重新核准都不會變。切換完成時平台會通知租戶。建立標籤(POST /v1/tags)不受這個限制。
lightup.tag.write與lightup.tag.define2026-10-26 由規劃轉為預覽;帶著它們的發版部署完成之前,打這五個操作仍回 404(路由還沒有掛上)。要用到它們,租戶要核准這兩項(2026-10-26 之前記錄的「開全部」不含它們)。
標籤成員:PUT/DELETE /v1/persons/{personId}/tags/{tagId}、POST /v1/tags/{tagId}/members:add、:remove
PUT https://api.lightup.tech/v1/persons/{personId}/tags/{tagId}
Authorization: Bearer <workload token>
Idempotency-Key: 5d7c0b0e-8a33-4b1c-9b0e-2f2f0b0e8a33
Idempotency-Key 必填,而且必須是 UUID:只接受有連字號的 8-4-4-4-12 寫法,十六進位大小寫皆可,不可以是全零的 UUID。這和訂單的 key(1–200 個可見 ASCII 字元)規則不同:其他形狀的值,即使在訂單上合法,在這裡也是 422 schema_invalid,而且在判權之前就回。
| 情境 | 結果 |
|---|---|
| 第一次送出這個 key | 照做;單一寫入回 changed: true(已經是那個狀態時 changed: false) |
| 同一個 key、同一個寫入重送 | 不會再寫一次;單一寫入回 replayed: true |
| 同一個 key 用在不同的寫入上 | 409 idempotency_key_reused |
一個 key 綁定一個完整的請求。 所謂「不同的寫入」,指的是請求內容有任何不同:多一位或少一位客戶、換了標籤、換了 provenance,或者同一批人先加(members:add、PUT)再移(members:remove、DELETE)。這些全部回 409 idempotency_key_reused,而且什麼都不會寫。所以加和移要用不同的 key,每一個新的請求都要產生新的 UUID。同一批客戶只是順序不同、或清單裡有重複,仍然算同一個請求。
網路逾時而不知道寫入有沒有成功:用同一個 key 重送同一個寫入。不要為了「重試」換一個新的 key。
- 單一寫入(
PUT/DELETE)回{ "changed": …, "replayed": … }。 - 批次寫入(
members:add/:remove)一次最多 1000 位客戶,回{ "changed": …, "unchanged": …, "skipped": [...], "replayed": … }。replayed: true表示這批(或其中一部分)先前已用同一個 key 套用過、這次沒有重做;平台不保存第一次的回應,所以已套用那部分的人數與略過名單不會再出現,要完整名單請以第一次的回應為準。members:add另收選填的provenance([A-Za-z0-9._:-],1–128 字元,記錄這批成員是哪條規則或哪次匯入產生的)。每一位被略過的客戶都會列出原因:
reason |
意思 |
|---|---|
missing |
這個租戶沒有這位客戶 |
not_canonical |
這位客戶已被合併到另一位;改用合併後的 person id |
tag_limit |
這位客戶的標籤數已達上限 |
建立標籤:POST /v1/tags
{ "tagName": "永和 週六", "categoryNodeId": "node-7", "backgroundColor": "#12AB9F", "description": "選填說明" }
| 欄位 | 必填 | 說明 |
|---|---|---|
tagName |
是 | 先去掉前後空白,再檢查 1–100 字元、不含控制字元 |
categoryNodeId |
是 | 一個已經存在的標籤分類,來自 categories:lookup。不存在 → 422 category_not_found |
backgroundColor |
否 | #RRGGBB |
description |
否 | 最多 500 字元;去掉前後空白後為空,視同沒給 |
同一個分類下同一個名稱只會有一個標籤,所以重送是安全的,不需要 Idempotency-Key:
| 情境 | 結果 |
|---|---|
| 這次建立了新標籤 | 201,{ "tagId": "…", "created": true } |
| 這個分類下已經有同名標籤 | 200,created: false,回傳既有那一個的 tagId |
| 這個名稱對應的標籤 id 已被一個後來改名或搬走的標籤占用 | 409 tag_name_conflict |
錯誤處理
| 狀態與代碼 | 意思 | 怎麼做 |
|---|---|---|
401 invalid_token |
token 本身不可用 | 換一張新的機器 token,再試一次;仍失敗就停 |
403 profile_not_supported |
這是使用者本人的 token | 改用機器流程(workload)的 token |
403 capability_not_granted、plan_capability_excluded、tenant_not_enabled 等 |
授權或方案不准 | 不要重試。照錯誤・限流・重試的 403 表格,找租戶管理員處理 |
404 not_found |
標籤或客戶不存在,或不屬於這個租戶;或路徑上的 id 形狀不合 | 確認 id 來自平台,不是自己拼的 |
409 idempotency_key_reused |
同一個 key 用在了不同的寫入上 | 不要重送。要做另一個寫入,換一個新的 UUID |
409 tag_writes_not_open |
這個租戶的客戶在這裡還不能寫標籤成員(租戶的身分切換尚未完成)。是狀態,不是權限;建立標籤不受影響 | 不要重試;切換完成之前不要開始寫入標籤成員,等平台公告 |
409 person_merged |
這位客戶已被合併到另一位 | 改用合併後的 person id 再送 |
409 tag_name_conflict |
建立標籤時名稱對應的 id 已被別的標籤占用 | 不要重試同一份請求;確認分類與名稱 |
422 schema_invalid |
請求內容、查詢參數或標頭不符合 schema(包括未知的查詢參數、Idempotency-Key 不是有連字號的 UUID) |
照 OpenAPI 修正請求。不要原樣重送 |
422 tag_limit_reached |
這位客戶的標籤數已達上限 | 先移除不用的標籤 |
422 category_not_found |
指定的標籤分類不存在 | 用 categories:lookup 取得正確的分類 id;分類請由租戶在後台建立 |
429 rate_limited |
限流 | 依 Retry-After 等待後再試,加上抖動 |
503 authorization_unavailable |
現在判不了(授權服務或標籤服務暫時不可用) | 指數退避後重試。寫入的重試要用同一個 Idempotency-Key |
403 與 503 永遠不一樣:403 是「不准」,不會因為重試而變成允許;503 是「現在判不了」,應該重試。這條區分在錯誤・限流・重試有完整說明。