# 顧客、會員與權限

> One contact record per person, dynamic segments, passwordless customer sign-in and entitlements that decide who may access what.

> Markdown version of https://kanorio.com/zh-HK/developers/products/customers. Append `.md` to any developer docs URL for this format. Index: https://kanorio.com/llms.txt · MCP: https://app.kanorio.com/api/mcp
>
> Translated from the English original: https://kanorio.com/en/developers/products/customers.md

Status: **Available**

每位填寫表單、購買商品或登入的使用者都會成為一個聯絡人。Kanorio 會將他們的活動整合至該記錄中，而非針對各項功能維護獨立的列表。

## 核心物件

- **聯絡人 (Contacts)：** 包含姓名、電子郵件、電話、同意狀態與標籤，以及該使用者的訂單、表單提交記錄與課程進度。每個聯絡人皆可攜帶您系統的 ID (`externalId`，每個網站唯一且僅能設定一次) 以及用於整合欄位的扁平化 `metadata`，並具有登入狀態 (`accessStatus`)：被封鎖的聯絡人無法登入，但仍可接收郵件與處理訂單。
- **區隔 (Segments)：** 針對聯絡人設定的儲存篩選器，會自動更新，例如「本月購買課程的所有人」。
- **權限 (Entitlements)：** 授予聯絡人存取特定內容（如課程或會員專屬文章）的許可。購買行為會自動授予權限，您也可以手動授予或撤銷。
- **顧客工作階段 (Customer sessions)：** 顧客透過一次性驗證碼登入，並取得用於 Customer API 的 `knr_cat_` 權杖。

在 Kanorio 中，會員資格、訂閱、點數與權限是獨立的概念。權限僅用於判斷某人是否可存取特定內容；它絕不會被用作餘額或計費計劃。

## API 如何運作

- 使用 Management API 管理聯絡人、區隔與權限。
- 使用 Customer API 讓顧客登入並讀取其個人資料，或直接嵌入 `<kanorio-account>`（支援 Passkey、Google 與電子郵件驗證碼，具體取決於網站啟用的方法；`GET /site` 會在 `customerAccess.methods` 下列出這些方法）。
- 受限內容傳遞 API (Gated Content Delivery API) 讀取請求會使用顧客的權杖來判斷回傳內容。
- Webhooks 會回報聯絡人變更 (`customers.contact.created`、`updated`、`merged`、`access_changed`)、行銷同意變更 (`customers.consent.updated`) 以及權限的授予與撤銷。聯絡人酬載 (payload) 僅包含 ID 與欄位名稱，絕不會包含電子郵件地址或電話號碼；請透過 API 取得聯絡人以讀取數值。

## What the APIs expose

| Capability | Status | API | Elements | Hosted site | Webhooks |
| --- | --- | --- | --- | --- | --- |
| Contacts & dynamic segments (external reference, metadata, sign-in status, manual merge) | Available | Management API `contacts.*` (`externalId`, `metadata`, look-up by `externalId`), `segments.*` | — | `/customers/contacts`, `/data/contacts`, `/data/segments` | `customers.contact.created`, `customers.contact.updated`, `customers.contact.merged`, `customers.contact.access_changed`, `customers.consent.updated`, `customers.form.submitted` |
| Customer login (magic link / 6-digit code) | Available | Customer `POST /auth/challenge`, `POST /auth/verify` → Bearer; `GET /me`; `DELETE /session` | `<kanorio-login>` (stores Bearer in localStorage, `kanorio:login` event) | `/account/login` | — |
| Entitlements (who may access what) | Available | Management API `entitlements.grant` / `revoke` / `list` / `check`; Customer `GET /access/:id` | `<kanorio-unit>` shows locked / preview / not-released states | Backoffice contact → Access tab; `/data/entitlements`; `/account/content` | `deliverables.entitlement.granted`, `deliverables.entitlement.revoked` |
| Membership tiers (ranked segments & automatic perks) | Planned | Planned (`tiers.*`) | — | Planned (`/data/tiers`) | — |

## API reference

- Management API: [Contacts](https://kanorio.com/en/developers/management-api/contacts) (5 operations)
- Management API: [Segments](https://kanorio.com/en/developers/management-api/segments) (1 operations)
- Management API: [Entitlements](https://kanorio.com/en/developers/management-api/entitlements) (4 operations)
- Customer API: [Openapi](https://kanorio.com/en/developers/customer-api/openapi) (1 operations)
- Customer API: [Auth](https://kanorio.com/en/developers/customer-api/auth) (6 operations)
- Customer API: [Passkeys](https://kanorio.com/en/developers/customer-api/passkeys) (4 operations)
- Customer API: [Me](https://kanorio.com/en/developers/customer-api/me) (1 operations)
- Customer API: [Session](https://kanorio.com/en/developers/customer-api/session) (1 operations)
- Customer API: [Access](https://kanorio.com/en/developers/customer-api/access) (1 operations)

## Webhook events

- `customers.sharedSender.softCap`: Fired once per day when sign-in code and similar emails sent from Kanorio's shared address exceed the site's daily soft cap; the bot check before sign-in is strengthened automatically. Nothing to do.
- `customers.sharedSender.paused`: Fired when those emails are paused for the site because of bounces, complaints or unusual volume; passkey, Google and signed-in customers are unaffected. Kanorio reviews and restores sending.
- `customers.sharedSender.resumed`: Fired when paused sign-in code emails resume after review.
- `customers.contact.created`: Fired when a contact is created from any source (checkout, form, import, manual, customer sign-up). Identities are listed by kind only; the data never includes the email address or phone number.
- `customers.contact.updated`: Fired when a contact's fields change (name, tags, note, locale, invoice preference, metadata, external reference, profile attributes). Lists the changed field names; fetch the contact to read the values.
- `customers.contact.merged`: Fired when two contacts become one, either automatically (the same person arrived with another identity) or by the owner. mergedContactId no longer exists; move your references to contactId.
- `customers.contact.access_changed`: Fired when the owner blocks or unblocks a customer's sign-in. BLOCKED revokes every session and refuses new sign-ins; orders, consent and emails are unaffected.
- `customers.consent.updated`: Fired when a contact's marketing consent on one channel changes (subscribed, pending confirmation, unsubscribed, bounced, complained).
- `deliverables.entitlement.granted`: Fired when a contact is granted access (Entitlement) to a deliverable or unit.
- `deliverables.entitlement.revoked`: Fired when a contact's Entitlement is revoked (e.g. refund or manual revocation).

Payloads: https://kanorio.com/en/developers/webhooks/events

## Elements

- `<kanorio-account>`: Customer sign-in panel: passkey, Google and a 6-digit email code, in the order the site enables them; signed-in customers see the account menu. Stores the customer token in localStorage and fires kanorio:login and kanorio:logout.
- `<kanorio-login>`: Deprecated alias of kanorio-account kept for pages that already embed it; same panel, same events.

## Recent changes

- 2026-11-03: Contacts: external references, metadata, sign-in status and contact webhooks
- 2026-10-31: Contacts: contacts.update replaces contacts.update_tags_note and can set the name
- 2026-10-27: entitlements.grant: bring-your-own payments (source EXTERNAL), idempotency keys

Full changelog: https://kanorio.com/en/developers/changelog

## For site owners

Dashboard help: https://kanorio.com/zh-HK/help/customers