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

標籤與顧客(預覽)

狀態:預覽(preview),2026-10-19 加入;兩項寫入能力 2026-10-26 由規劃(planned)轉為預覽。 這些能力的契約已定案、可以呼叫,但尚未適用正式版的支援與棄用保證:欄位、錯誤細節與行為在轉為 ga 之前仍可能調整,調整會照版本與棄用公告。標籤成員的寫入在租戶的身分切換完成之前一律被拒(409 tag_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 沒有建立或修改標籤分類、改標籤名稱、刪除標籤的操作;分類請由租戶在後台建立。

範圍與授權

共同規則

列出帶著某個標籤的客戶: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"
}

讀取客戶帶著的標籤: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" }

每個名稱回一個結果:

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"] }

每個 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

列出客戶監護中的孩子:GET /v1/persons/{personId}/wards

能力 lightup.person.wards.read,預覽,2026-10-28 加入。

{
  "guardian": { "personId": "psn_01j8m4k2r7e9v3xq5w8n0tza6b" },
  "wards": [
    {
      "personId": "psn_01j8m4k2r7e9v3xq5w8n0tza6c",
      "givenName": "小明",
      "familyName": "王",
      "displayName": "王小明",
      "birthDate": "2019-04-07",
      "gender": "male"
    }
  ],
  "truncated": false
}

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 這位客戶取消訂閱 不要送

寫入

租戶的身分切換完成之前,不要開始寫入標籤成員。 下面四個成員寫入(PUT/DELETE /v1/persons/{personId}/tags/{tagId}、members:add、:remove)在租戶的身分切換完成之前一律回 409 tag_writes_not_open:這是租戶的狀態,不是權限問題,重試、換 token 或重新核准都不會變。切換完成時平台會通知租戶。建立標籤(POST /v1/tags)不受這個限制。

lightup.tag.write 與 lightup.tag.define 2026-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。

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 是「現在判不了」,應該重試。這條區分在錯誤・限流・重試有完整說明。

注意事項