FastComments 的 API
FastComments 提供一個可與多種資源互動的 API。可用來建立與我們平台的整合，或甚至自行建立客戶端！
在本文件中，您將會找到 API 支援的所有資源，並列出它們的請求與回應類型。
對於企業客戶，所有 API 存取都會被記錄在稽核日誌中。
已產生的 SDKs
FastComments 現在會從程式碼產生一份 API Spec（尚未完整，但已包含許多 API）。
我們也提供熱門語言的 SDK：
- fastcomments-cpp
- fastcomments-go
- fastcomments-java
- fastcomments-sdk-js
- fastcomments-nim
- fastcomments-php
- fastcomments-php-sso
- fastcomments-python
- fastcomments-ruby
- fastcomments-rust
- fastcomments-swift
驗證
API 的驗證方式是將您的 api key 以 X-API-KEY 標頭或 API_KEY 查詢參數傳送。您還需要您的 tenantId 來進行 API 呼叫。這可以從與您的 api key 相同的頁面取得。
安全注意事項
這些路由應從 伺服器 呼叫。 請勿 從瀏覽器呼叫它們。這樣做會暴露您的 API key - 任何能查看頁面原始碼的人都會取得對您帳戶的完全存取權！
驗證選項一 - 標頭
- 標頭:
X-API-KEY - 標頭:
X-TENANT-ID
驗證選項二 - 查詢參數
- 查詢參數:
API_KEY - 查詢參數:
tenantId
API 資源 
資源使用
請注意，從 API 擷取資料會計入您帳戶的使用量。
每個資源會在其專屬章節列出該使用量。
有些資源的服務成本高於其他資源。每個端點在每次 API 呼叫時都有固定的點數成本。對於某些端點，點數數量 會根據選項和回應大小而變化。
API 使用情況可在 帳單分析 頁面檢查，且每幾分鐘更新一次。
注意！
我們建議先閱讀 Pages 文件，以便在為 Comment API 傳入 urlId 值時減少混淆。
彙整您的資料
Resource: Aggregate as GET /api/v1/aggregate Credit Cost: 1
此 API 會對文件進行彙總（若提供 groupBy 則會先分群），並套用多個運算。支援不同的運算（例如 sum、countDistinct、avg 等）。
費用為 可變。每掃描 500 個物件會耗費 1 個 API 點數。
預設每次 API 呼叫可使用的最大記憶體為 64MB，並且預設同一時間只允許一個彙總在執行。若同時提交多個彙總，將會排入佇列並依提交順序執行。待處理的彙總最多會等待 60 秒，超過後請求將會逾時。單一彙總最多可執行 5 分鐘。
若您有管理的租戶，可在一次呼叫中透過傳遞 parentTenantId 查詢參數來彙總所有子租戶的資源。
範例
範例：計算唯一值
計算唯一值 cURL 範例
Copy 
1
2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
3 "resourceName": "Comment",
4 "operations": [
5 { "op": "distinct", "field": "urlId", "alias": "urlId" },
6 { "op": "distinct", "field": "commenterEmail", "alias": "commenterEmail" }
7 ]
8}'
9
計算唯一值 回應
Copy
1
2{
3 "status": "success",
4 "data": [
5 {
6 "commenterEmail": {
7 "distinctCounts": {
8 "someone@somewhere.com": 1,
9 "someone2@somewhere.com": 1
10 }
11 }
12 },
13 {
14 "urlId": {
15 "distinctCounts": {
16 "some-page": 2
17 }
18 }
19 }
20 ],
21 "stats": { "scanned": 2 }
22}
23
範例：計算不同值
計算不同值 cURL 範例
Copy
1
2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
3 "resourceName": "Comment",
4 "operations": [
5 { "op": "countDistinct", "field": "urlId", "alias": "urlId" },
6 { "op": "countDistinct", "field": "commenterEmail", "alias": "commenterEmail" }
7 ]
8}'
9
Response:
計算不同值 回應
Copy
1
2{
3 "status": "success",
4 "data": [
5 {
6 "commenterEmail": { "distinctCount": 2 },
7 "urlId": { "distinctCount": 1 }
8 }
9 ],
10 "stats": { "scanned": 2 }
11}
12
範例：多欄位加總值
加總值 cURL 範例
Copy
1
2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
3 "resourceName": "Comment",
4 "operations": [
5 { "op": "sum", "field": "votes", "alias": "votes" },
6 { "op": "sum", "field": "votesUp", "alias": "votesUp" }
7 ]
8}'
9
Response:
加總值 回應
Copy
1
2{
3 "status": "success",
4 "data": [
5 {
6 "votes": { "numericValue": 2 },
7 "votesUp": { "numericValue": 2 }
8 }
9 ],
10 "stats": { "scanned": 2 }
11}
12
範例：多欄位平均值
平均值 cURL 範例
Copy
1
2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
3 "resourceName": "Comment",
4 "operations": [
5 { "op": "avg", "field": "votes", "alias": "votes" },
6 { "op": "avg", "field": "votesUp", "alias": "votesUp" }
7 ]
8}'
9
Response:
平均值 回應
Copy
1
2{
3 "status": "success",
4 "data": [
5 {
6 "votes": { "numericValue": 1 },
7 "votesUp": { "numericValue": 1 }
8 }
9 ],
10 "stats": { "scanned": 2 }
11}
12
範例：多欄位最小/最大值
最小/最大值 cURL 範例
Copy
1
2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
3 "resourceName": "Comment",
4 "operations": [
5 { "op": "min", "field": "votes", "alias": "votes" },
6 { "op": "min", "field": "votesUp", "alias": "votesUp" },
7 { "op": "max", "field": "votes", "alias": "votes" },
8 { "op": "max", "field": "votesUp", "alias": "votesUp" }
9 ]
10}'
11
Response:
最小/最大值 回應
Copy
1
2{
3 "status": "success",
4 "data": [
5 {
6 "votes": { "numericValue": 0 },
7 "votesUp": { "numericValue": 0 },
8 "votes": { "numericValue": 2 },
9 "votesUp": { "numericValue": 2 }
10 }
11 ],
12 "stats": { "scanned": 2 }
13}
14
範例：多欄位唯一值計數
計算唯一值 cURL 範例
Copy
1
2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
3 "resourceName": "Comment",
4 "operations": [
5 { "op": "distinct", "field": "urlId", "alias": "urlId" },
6 { "op": "distinct", "field": "commenterEmail", "alias": "commenterEmail" }
7 ]
8}'
9
Response:
計算唯一值 回應
Copy
1
2{
3 "status": "success",
4 "data": [
5 {
6 "commenterEmail": {
7 "distinctCounts": {
8 "someone@somewhere.com": 1,
9 "someone2@somewhere.com": 1
10 }
11 },
12 "urlId": {
13 "distinctCounts": {
14 "some-page": 2
15 }
16 }
17 }
18 ],
19 "stats": { "scanned": 2 }
20}
21
範例：建立查詢
建立查詢 cURL 範例
Copy
1
2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
3 "resourceName": "Comment",
4 "groupBy": ["commenterName"],
5 "query": [
6 { "key": "approved", "value": true, "operator": "eq" },
7 { "key": "commenterName", "value": "some-username-2", "operator": "eq" }
8 ],
9 "operations": [
10 { "op": "sum", "field": "votes", "alias": "votes" }
11 ]
12}'
13
Response:
建立查詢 回應
Copy
1
2{
3 "status": "success",
4 "data": [
5 {
6 "groups": { "commenterName": "some-username-2" },
7 "votes": { "numericValue": 2 }
8 }
9 ],
10 "stats": { "scanned": 1 }
11}
12
範例：計算待審核評論
計算待審核評論 cURL 範例
Copy
1
2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
3 "resourceName": "Comment",
4 "query": [
5 { "key": "reviewed", "value": true, "operator": "not_eq" }
6 ],
7 "operations": [
8 { "op": "count", "field": "id", "alias": "count" }
9 ]
10}'
11
Response:
計算待審核評論 回應
Copy
1
2{
3 "status": "success",
4 "data": [
5 { "count": { "numericValue": 2 } }
6 ],
7 "stats": { "scanned": 2 }
8}
9
範例：已核准、已審核與垃圾評論的分類統計
評論分類統計 cURL 範例
Copy
1
2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
3 "resourceName": "Comment",
4 "operations": [
5 { "op": "distinct", "field": "approved", "alias": "approved" },
6 { "op": "distinct", "field": "reviewed", "alias": "reviewed" },
7 { "op": "distinct", "field": "isSpam", "alias": "isSpam" }
8 ]
9}'
10
Response:
評論分類統計 回應
Copy
1
2{
3 "status": "success",
4 "data": [
5 {
6 "approved": { "distinctCounts": { "true": 2 } },
7 "reviewed": { "distinctCounts": { "false": 2 } },
8 "isSpam": { "distinctCounts": { "false": 2 } }
9 }
10 ],
11 "stats": { "scanned": 2 }
12}
13
結構
彙總請求 結構
Copy
1
2export type AggregationOpType = 'sum' | 'countDistinct' | 'distinct' | 'avg' | 'min' | 'max' | 'count';
3
4/** 將套用於欄位的運算 */
5export interface AggregationOperation {
6 /** 要操作的欄位 */
7 field: string;
8 /** 運算的類型 */
9 op: AggregationOpType;
10 /** 輸出的可選別名；若未提供會計算預設別名 */
11 alias?: string;
12 expandArray?: boolean;
13}
14
15export interface QueryPredicate {
16 key: string
17 value: string | number | boolean
18 operator: 'eq' | 'not_eq' | 'greater_than' | 'less_than' | 'contains'
19}
20
21export interface AggregationRequest {
22 query?: QueryPredicate[];
23 resourceName: string;
24 groupBy?: string[];
25 operations: AggregationOperation[];
26 sort?: {
27 field: string;
28 dir: 'asc' | 'desc';
29 };
30}
31
32type DistinctAccumulator = Record<string, number>;
33type GroupValues = Record<string, string>;
34
35export type AggregationValue = {
36 distinctCounts?: DistinctAccumulator
37 distinctCount?: number
38 numericValue?: number
39 stringValue?: string
40 groups?: GroupValues
41};
42
彙總回應 結構
Copy
1
2export type AggregationItem = Record<string, AggregationValue> & { groups?: GroupValues };
3
4export interface AggregationResponse {
5 status: APIStatus,
6 data: AggregationItem[];
7 stats?: {
8 scanned: number;
9 timeMS: number;
10 };
11}
12
The following resources can be aggregated:
- AffiliateEvent
- AnonymousVote
- BannedUser
- BatchJob
- BlockedUser
- Comment
- CommentDeleted
- CommentIdToSyncOutbound
- CommentScheduled
- CommentSyncLog
- CustomConfig
- CustomEmailTemplateRenderError
- EmailToSend
- EventLogEntry
- ImportedCommentScheduled
- ModerationGroup
- Moderator
- Page
- PageReact
- PendingVote
- QuestionResult
- SSOUser
- SentEmail
- SpamEvent
- Tenant
- TenantAuditLog
- TenantBadge
- TenantDailyUsage
- TenantInvoiceHistory
- TenantPackage
- User
- UserBadge
- UserBadgeProgress
- UserNotification
- UserSubscription
- UserUsage
- Vote
稽核日誌結構
An AuditLog 是一個物件，代表對有權使用此功能的租戶所記錄的稽核事件。
The structure for the AuditLog object is as follows:
AuditLog 結構
Copy
1
2interface AuditLog {
3 id: string;
4 userId?: string;
5 username?: string;
6 resourceName: string;
7 crudType: 'c' | 'r' | 'u' | 'd' | 'login';
8 from: string;
9 url?: string;
10 ip?: string;
11 when: string;
12 description?: string;
13 serverStartDate: string;
14 objectDetails?: object;
15}
16
稽核日誌是不可變的。也無法手動寫入。FastComments.com 可能是唯一能決定何時寫入稽核日誌的實體。不過，你可以透過此 API 讀取它。
Events in the audit log expire after two years.
GET /api/v1/audit-logs
Resource: AuditLog as GET /api/v1/audit-logs Credit Cost: 10
此 API 使用分頁，由 skip、before 與 after 參數提供。AuditLogs 會以每頁 1000 筆回傳，依 when 與 id 排序。
每取得 1000 筆日誌會花費 10 點額度。
預設會以 最新項目在前 的方式回傳清單。如此一來，您可以從 skip=0 開始輪詢，分頁直到找到您已消費的最後一筆紀錄。
或者，您可以將排序改為最舊優先，然後分頁直到沒有更多紀錄。
可透過將 order 設為 ASC 或 DESC 來設定排序。預設為 ASC。
可以使用帶毫秒的時間戳記透過 before 與 after 查詢日期。before 與 after 不包含邊界值。
AuditLog cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/audit-logs?tenantId=demo&API_KEY=DEMO_API_SECRET&skip=0&order=ASC&before=123&after=456'
4
AuditLog 請求結構
Copy
1
2interface CommentsRequestQueryParams {
3 tenantId: string
4 API_KEY: string
5 order?: 'ASC' | 'DESC'
6 skip?: number
7 before?: number
8 after?: number
9}
10
AuditLog 回應結構
Copy
1
2interface CommentsResponse {
3 status: 'success' | 'failed'
4 /** 失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
6 /** 失敗時包含。 **/
7 reason?: string
8 /** 日誌！ **/
9 auditLogs: AuditLog[]
10}
11
評論結構
一個 Comment 物件代表使用者留下的評論。
父子評論之間的關係由 parentId 定義。
Comment 物件的結構如下：
評論結構
Copy
1
2interface Comment {
3 /** 唯讀：如果垃圾郵件引擎判定此評論為垃圾郵件，則設為 true。 **/
4 aiDeterminedSpam?: boolean
5 /** 評論是否核准顯示。儲存評論時設為 true，否則會被隱藏。 **/
6 approved?: boolean
7 /** 使用者的大頭貼。 **/
8 avatarSrc?: string
9 /** 子評論。並非在所有情況下皆會填入。當透過 API 將 asTree 設為 true 時使用。 **/
10 children: Comment[]
11 /** 評論者的原始評論文字。 **/
12 comment: string
13 /** 唯讀：評論者的評論解析後的 HTML。 **/
14 commentHTML?: string
15 /** 評論者的電子郵件。若匿名評論被關閉則為必填。 **/
16 commenterEmail?: string
17 /** 評論者的連結（例如，他們的部落格）。 **/
18 commenterLink?: string
19 /** 評論者的名稱。始終為必填。如果沒有，可設為像 "Anonymous" 之類的名稱。 **/
20 commenterName: string
21 /** 留下評論的日期，以 UTC epoch 表示。 **/
22 date: number
23 /** 評論的「顯示標籤」，例如 "Admin"、"Moderator"，或像 "VIP User" 之類的。 **/
24 displayLabel?: string
25 /** 發表評論的網域。 **/
26 domain?: string
27 /** 唯讀：評論被檢舉的次數。 **/
28 flagCount?: number
29 /** 評論中成功解析的 #hashtag。你也可以手動加入 hashtag 以供查詢，但它們不會自動顯示在評論文字中。 **/
30 hashTags?: CommentHashTag[]
31 /** 唯讀：評論是否包含圖片？ **/
32 hasImages?: boolean
33 /** 唯讀：評論是否包含連結？ **/
34 hasLinks?: boolean
35 /** 唯讀：唯一的評論 id。 **/
36 id: string
37 /** 僅在建立時使用！此欄位會被雜湊後儲存。 **/
38 ip?: string
39 /** 唯讀：目前使用者是否封鎖了撰寫此評論的使用者？ **/
40 isBlocked?: boolean
41 /** 唯讀：此評論是否由管理員發表？會根據 userId 自動設定。 **/
42 isByAdmin?: boolean
43 /** 唯讀：此評論是否由版主發表？會根據 userId 自動設定。 **/
44 isByModerator?: boolean
45 /** 若評論已被軟刪除（因其他設定需保留代表項），則設為 true。 **/
46 isDeleted?: boolean
47 /** 若使用者帳戶被刪除但評論需被保留，則設為 true。 **/
48 isDeletedUser?: boolean
49 /** 唯讀：是否已被當前登入使用者（contextUserId）檢舉？ **/
50 isFlagged?: boolean
51 /** 評論是否被置頂？ **/
52 isPinned?: boolean
53 /** 評論是否鎖定以禁止新回覆（版主仍可回覆）？ **/
54 isLocked?: boolean
55 /** 此評論是否為垃圾郵件？ **/
56 isSpam?: boolean
57 /** 唯讀：對於當前使用者（contextUserId），此評論是否被投下反對票？ **/
58 isVotedDown?: boolean
59 /** 唯讀：對於當前使用者（contextUserId），此評論是否被投下贊成票？ **/
60 isVotedUp?: boolean
61 /** 評論所使用的語系。若未提供，將從 Accept-Language HTTP 標頭推斷。 **/
62 locale?: 'de_de' | 'en_us' | 'es_es' | 'fr_fr' | 'it_it' | 'ja_jp' | 'ko_kr' | 'pl_pl' | 'pt_br' | 'ru_ru' | 'tr_tr' | 'zh_cn' | 'zh_tw'
63 /** 唯讀：評論中成功解析的 @提及。 **/
64 mentions?: CommentUserMention[]
65 /** 與評論相關的可選額外資訊（metadata）。 **/
66 meta?: Record<string, string | number | boolean>
67 /** 與此評論相關的可選 moderation 群組 id 清單。 **/
68 moderationGroupIds?: string[]|null
69 /** 唯讀：對應於當前使用者（contextUserId）在此評論上投票的 vote 物件 id。 **/
70 myVoteId?: string
71 /** 是否已針對評論者發送此評論的通知。為了在匯入時避免發送通知，請將此設為 true。 **/
72 notificationSentForParent?: boolean
73 /** 是否已針對租戶使用者發送此評論的通知。為了在匯入時避免發送通知，請將此設為 true。 **/
74 notificationSentForParentTenant?: boolean
75 /** 此評論所屬頁面的標題。 **/
76 pageTitle?: string
77 /** 若為回覆某則評論，這是被回覆的評論 ID。 **/
78 parentId?: string|null
79 /** 評論是否被標示為已審核。 **/
80 reviewed: boolean
81 /** 評論所屬的租戶 id。 **/
82 tenantId: string
83 /** 撰寫評論的使用者。當以名稱/電子郵件儲存評論時會自動建立。 **/
84 userId?: string|null
85 /** 此評論可見的對應位置 URL，例如部落格文章。 **/
86 url: string
87 /** 你傳入的 urlId 經過「清理」後的版本。儲存時你會指定此欄位，但當取回評論時，這會是「清理」後的值，而你原本的值會移到 urlIdRaw。 **/
88 urlId: string
89 /** 唯讀：你傳入的原始 urlId。 **/
90 urlIdRaw?: string
91 /** 使用者及此評論是否已驗證？ **/
92 verified: boolean
93 /** 讚成票數。 **/
94 votesUp?: number
95 /** 反對票數。 **/
96 votesDown?: number
97 /** 評論的「Karma」（= 讚成票數 - 反對票數）。 **/
98 votes?: number
99}
100
Some of these fields are marked READONLY - these are returned by the API but cannot be set.
評論文字結構
評論以 FastComments 風格的 Markdown 撰寫，這就是 Markdown 加上傳統的 bbcode 風格圖片標籤，例如 [img]path[/img]。
文字會儲存在兩個欄位。使用者輸入的文字以未修改的形式儲存在 comment 欄位；渲染後的內容則儲存在 commentHTML 欄位。
允許的 HTML 標籤有 b, u, i, strike, pre, span, code, img, a, strong, ul, ol, li, and br。
建議將 HTML 渲染出來，因為它只是 HTML 的一個非常小的子集，構建渲染器相當直接。舉例來說，有多個可用於 React Native 與 Flutter 的函式庫可以協助完成這件事
你也可以選擇渲染 comment 欄位未標準化的值。範例解析器在這裡。。
該範例解析器也可以調整以支援 HTML，並將 HTML 標籤轉換為你平台期待渲染的元素。
標註
當使用者在評論中被標註時，相關資訊會儲存在名為 mentions 的清單中。該清單中的每個物件具有以下結構。
評論提及物件
Copy Run 
Run 1
2interface CommentUserMention {
3 /** 使用者 id。對於 SSO 使用者，會加上你的租戶 id 前綴。 **/
4 id: string
5 /** 最終的 @提及 標籤文字，包含 @ 符號。 **/
6 tag: string
7 /** 原始的 @提及 標籤文字，包含 @ 符號。 **/
8 rawTag: string
9 /** 被標註的使用者類型。user = FastComments.com 帳戶。sso = SSOUser。 **/
10 type: 'user'|'sso'
11 /** 即使使用者選擇不接收通知，這仍會被設為 true。 **/
12 sent: boolean
13}
14
HashTags
當使用 hashtag 並成功解析時，相關資訊會儲存在名為 hashTags 的清單中。該清單中的每個物件具有以下結構。若將 retain 設定為 true，hashtag 也可以手動加入至評論的 hashTags 陣列以供查詢。
評論 Hashtag 物件
Copy Run
Run 1
2interface CommentHashTag {
3 /** hashtag id。 **/
4 id: string
5 /** 最終的 #hashtag 標籤文字，包含 # 符號。 **/
6 tag: string
7 /** 若該 hashtag 與自訂 URL 關聯，則會定義此欄。 **/
8 url?: string
9 /** 當評論更新時，若需保留該 hashtag（即使它不存在於評論文字中），則設定此欄。這對於在不更改評論文字的情況下標註評論很有用。 **/
10 retain?: boolean
11}
12
GET /api/v1/comments
Resource: Comment as GET /api/v1/comments Credit Cost: 1
此 API 用於取得要顯示給使用者的留言。例如，它會自動過濾未核准或垃圾留言。
分頁
分頁可以用兩種方式之一，取決於效能需求和使用情境：
- Fastest: Precalculated Pagination:
- 這是當您使用我們預建的小工具與客戶端時 FastComments 的運作方式。
- 點擊「下一頁」只是簡單地增加頁數。
- 你可以把這視為由鍵值儲存取得。
- 因此，只需定義從
0開始的page參數和一個作為direction的排序方向。 - 頁面大小可透過自訂規則進行調整。
- Most Flexible: Flexible Pagination:
- 在這種方式中你可以定義自訂的
limit和skip參數。不要傳遞page。 - 也支援排序
direction。 limit是在套用skip後要回傳的總數。- 例子：當
page size = 100且page = 2時，設定skip = 200, limit = 100。
- 例子：當
- 子留言仍會被計入分頁。你可以使用
asTree選項來避開這點。- 你可以透過
limitChildren和skipChildren對子留言進行分頁。 - 你可以透過
maxTreeDepth限制回傳的討論串深度。
- 你可以透過
- 在這種方式中你可以定義自訂的
討論串
- 當使用
Precalculated Pagination時，留言會以「頁」分組，而討論串內的留言會影響整體頁面。- 如此一來，客戶端可根據
parentId判斷討論串。 - 例如，某頁有一則頂層留言與 29 則回覆，並在 API 中設定
page=0— 你會只得到該頂層留言與 29 個子留言。 - 範例圖片，說明多頁情形。
- 如此一來，客戶端可根據
- 當使用
Flexible Pagination時，你可以定義parentId參數。- 將其設為 null 以僅取得頂層留言。
- 然後要查看討論串時，再次呼叫 API 並傳入
parentId。 - 常見的解法是先對頂層留言進行 API 呼叫，然後並行對每則留言的子留言進行 API 呼叫。
- NEW As of Feb 2023! 使用
&asTree=true以樹狀方式取得。- 你可以把這視為
Flexible Pagination as a Tree。 - 分頁僅計算頂層留言。
- 將
parentId=null設為樹的根（你必須設定parentId）。 - 設定
skip和limit以進行分頁。 - 將
asTree設為true。 - 消耗的信用額度會增加為
2x，因為後端在此情況下須做更多工作。 - 視需要設定
maxTreeDepth、limitChildren及skipChildren。
- 你可以把這視為
樹狀結構說明
當使用 asTree 時，理解分頁可能會比較困難。這裡有一張方便的圖示：
樹狀分頁示意圖
在使用者情境下取得留言
/comments API 可用於兩種情境，對應不同的使用案例：
- 用於回傳已排序並標記附加資訊以便建構你自己的客戶端的留言。
- 在這種情況下，定義一個
contextUserId查詢參數。
- 在這種情況下，定義一個
- 用於從你的後端擷取留言以做自訂整合。
- 若未提供
contextUserId，平台預設會採用此方式。
- 若未提供
留言：預先計算分頁
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&page=0&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR'
4
留言：彈性分頁
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10'
4
留言：使用者情境下的彈性分頁
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id'
4
留言：使用者情境下僅頂層留言的彈性分頁
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null'
4
以樹狀取得留言
可以將回傳的留言以樹狀結構呈現，分頁只計算頂層留言。
留言：使用者情境下的樹狀取得
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null&asTree=true'
4
想只取得頂層留言與其直接子留言？以下是一種方式：
留言：樹狀取得（最大深度）
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null&asTree=true&maxTreeDepth=1&limitChildren=10'
4
不過在你的 UI 中你可能需要知道是否要在每則留言上顯示「顯示回覆」按鈕。當以樹狀方式擷取留言時，適用時會在留言上附加 hasChildren 屬性。
以樹狀取得留言，依標籤搜尋
可以使用 API 依標籤搜尋整個租戶中的留言（不侷限於單一頁面或 urlId）。
在此範例中，我們省略了 urlId，並以多個標籤進行搜尋。API 只會回傳具有所有請求標籤的留言。
留言：使用者情境下依標籤的樹狀取得
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null&asTree=true&hashTag=TestTag&hashTag=OtherTestTag'
4
所有請求參數
留言請求結構
Copy
1
2interface CommentsRequestQueryParams {
3 tenantId: string
4 API_KEY: string
5 /** 留言所關聯的 urlId（頁面 URL 或文章 ID）。 **/
6 urlId?: string
7 /** 限制由此使用者回傳的留言。 **/
8 userId?: string
9 /** 用此參數以標籤搜尋。要縮小至多個標籤的交集，使用 &hashTag=a&hashTag=b。 **/
10 hashTag?: string
11 /** 排序方向。預設為 MR（最相關）。其他選項為 OF（最舊優先）和 NF（最新優先）。 **/
12 direction?: 'MR' | 'OF' | 'NF'
13 /** 預先計算分頁：要擷取的頁面，從 0 開始。傳入 -1 可取得所有留言（最多 250 筆）。 **/
14 page?: number
15 /** 彈性分頁：我們應回傳多少則留言？ **/
16 limit?: number
17 /** 彈性分頁：對每個父留言應回傳多少子留言？ **/
18 limitChildren?: number
19 /** 彈性分頁：應跳過多少則留言？ **/
20 skip?: number
21 /** 彈性分頁：對每個父留言應跳過多少子留言？ **/
22 skipChildren?: number
23 /** 用於判定被封鎖或被檢舉的留言。 **/
24 contextUserId?: string
25 /** 用於判定被封鎖或被檢舉的留言。 **/
26 anonUserId?: string
27 /** 用於擷取子留言。 **/
28 parentId?: string
29 /** 用於以樹狀格式擷取。 **/
30 asTree?: boolean
31 /** 要在樹狀結構中回傳到多深？0 會不回傳任何子留言。1 會回傳直接子留言，依此類推。 **/
32 maxTreeDepth?: number
33}
34
回應
留言回應結構
Copy
1
2interface CommentsResponse {
3 status: 'success' | 'failed'
4 /** 失敗時會包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'missing-date' | 'unauthorized-page' | 'invalid-pagination-request' | 'invalid-limit' | 'invalid-limit-children' | 'invalid-skip' | 'invalid-skip-children' | 'invalid-max-tree-depth'
6 /** 失敗時會包含。 **/
7 reason?: string
8 /** 留言！ **/
9 comments: Comment[]
10}
11
有用的小提示
URL ID
你可能會想在呼叫 Comment API 時使用 urlId 參數。你可以先呼叫 Pages API，查看可用的 urlId 值長什麼樣子。
匿名操作
對於匿名留言，你可能會想在取得留言以及進行檢舉和封鎖時傳入 anonUserId。
(!) 許多應用商店要求如此，因為使用者必須能夠檢舉他們能看到的使用者產生內容，即使他們沒有登入。不這樣做可能會導致你的應用被該商店移除。
留言未被回傳
請確認你的留言是否已核准，且不是垃圾留言。
GET /api/v1/comments/:id
Resource: Comment as GET /api/v1/comments/:id Credit Cost: 1
此 API 提供依 id 取得單一評論的功能。
按 ID 取得評論 cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/comments/some-id?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
按 ID 取得評論 請求結構
Copy
1
2interface CommentsGetByIdQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
按 ID 取得評論 回應結構
Copy
1
2interface CommentGetByIdResponse {
3 status: 'success' | 'failed'
4 /** 失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'missing-id'
6 /** 失敗時包含。 **/
7 reason?: string
8 /** 評論本身。 **/
9 comment?: Comment
10}
11
POST /api/v1/comments
Resource: Comment as POST /api/v1/comments Credit Cost: 1
此 API 端點提供建立評論的功能。
常見用例包括自訂使用者介面、整合或匯入。
注意事項：
- 如果需要，此 API 可以「即時」更新評論小工具（這會將
creditsCost從1增加到2）。 - 如果提供了 email，這個 API 會自動在系統中建立使用者物件。
- 嘗試儲存兩則使用不同 email 但相同使用者名稱的評論，第二則評論會發生錯誤。
- 如果您指定了
parentId，且子評論的notificationSentForParent為 false，我們將會為父評論發送通知。此操作每小時進行（我們會將通知批次一起發送以減少郵件數量）。 - 如果您想在建立使用者時發送歡迎郵件，或想發送評論驗證郵件，請在查詢參數中將
sendEmails設為true。 - 透過此 API 建立的評論將顯示在管理應用程式的 Analytics 與 Moderation 頁面中。
- 如果該設定已開啟，評論者名稱與評論文字中的「髒話」仍會被遮罩。
- 透過此 API 建立的評論仍可視需要進行垃圾訊息檢查。
- 若透過「自訂規則」管理頁面設定的配置（例如最大評論長度）將在此處套用。
要在評論小工具中顯示，提交的最小資料如下：
最小評論 POST cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "approved": true,
7 "comment": "some-comment",
8 "commenterName": "some-commenter-name",
9 "date": 1622644382148,
10 "urlId": "some-place",
11 "url": "https://exmaple.com/some-page",
12 "verified": true
13}'
14
更實際的請求範例如下：
評論 POST cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true&doSpamCheck=true' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "approved": true,
7 "avatarSrc": "https://static.fastcomments.com/1605337537848-DSC_0841.JPG",
8 "comment": "some-comment",
9 "commenterName": "some-commenter-name",
10 "commenterEmail": "fordperfect@spaceship.com",
11 "date": 1622644382148,
12 "isSpam": false,
13 "locale": "en_us",
14 "notificationSentForParent": true,
15 "notificationSentForParentTenant": true,
16 "reviewed": true,
17 "urlId": "some-place",
18 "url": "https://exmaple.com/some-page",
19 "verified": true,
20 "votes": 1,
21 "votesUp": 2,
22 "votesDown": 1,
23 "ip": "123.456.789.000"
24}'
25
評論 POST 請求結構
Copy
1
2interface CommentPostQueryParams {
3 tenantId: string
4 API_KEY: string
5 doSpamCheck?: 'true' | 'false'
6 /** 是否該評論應對在具有相同 urlId 的評論小工具實例中查看的使用者顯示為「即時」。NOTE: Doubles credit cost from 1 to 2. **/
7 isLive?: 'true' | 'false'
8 sendEmails?: 'true' | 'false'
9 populateNotifications?: 'true' | 'false'
10}
11
評論 POST 回應結構
Copy
1
2
3interface CommentPostResponse {
4 status: 'success' | 'failed'
5 /** 失敗時包含。 **/
6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-comment' | 'comment-too-big' | 'hash-tags-readonly' | 'mentions-readonly' | 'invalid-user' | 'unauthorized' | 'invalid-date' | 'invalid-name' | 'invalid-name-is-email' | 'banned' | 'invalid-email';
7 /** 失敗時包含。 **/
8 reason?: string
9 /** 建立的評論。 **/
10 comment?: Comment
11 /** 關聯的使用者，可能已存在或不存在。 **/
12 user?: User
13}
14
PATCH /api/v1/comments/:id
Resource: Comment as PATCH /api/v1/comments/:id Credit Cost: 1
此 API 端點提供更新單一留言的功能。
注意事項：
- 如需，此 API 可以使留言小工具「即時」更新（會將基本
creditsCost從1提高到2）。- 這可讓在不同頁面之間遷移留言成為「即時」（變更
urlId）。 - 遷移會額外花費
2點數，因為頁面會被預先計算，且這對 CPU 要求高。
- 這可讓在不同頁面之間遷移留言成為「即時」（變更
- 與建立 API 不同，若提供電子郵件，本 API 不會在我們系統中自動建立使用者物件。
- 透過本 API 更新的留言仍可在需要時進行垃圾留言檢查。
- 透過自訂規則（Customization Rule）管理頁面設定的配置（例如最大留言長度）也會在此適用。
- 若要允許使用者更新留言內容，只需在請求主體中指定
comment。我們將產生對應的commentHTML。- 如果同時定義
comment與commentHTML，我們將不會自動生成 HTML。 - 如果使用者在新文字中加入提及或主題標籤（hashtags），仍會像
POSTAPI 一樣進行處理。
- 如果同時定義
- 在更新留言的
commenterEmail時，最好同時指定userId。否則，您必須確保該電子郵件對應的使用者屬於您的租戶，否則請求將失敗。
最小評論 PATCH cURL 範例
Copy
1
2curl --request PATCH \
3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "comment": "some-new-comment-text"
7}'
8
評論 PATCH 請求結構
Copy
1
2interface CommentPatchQueryParams {
3 tenantId: string
4 API_KEY: string
5 /** 執行更新的使用者。若需要可用來檢查他們是否能編輯該留言。 **/
6 contextUserId?: string
7 /** 是否要檢查新留言是否看起來像垃圾留言？ **/
8 doSpamCheck?: 'true' | 'false'
9 /** 該留言是否應對使用相同 urlId 的留言小工具實例的使用者顯示為「即時」。注意：會將點數成本從 1 加倍為 2。 **/
10 isLive?: 'true' | 'false'
11}
12
評論 PATCH 回應結構
Copy
1
2
3interface CommentPatchResponse {
4 status: 'success' | 'failed'
5 /** 於失敗時包含。 **/
6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-comment' | 'comment-too-big' | 'hash-tags-readonly' | 'mentions-readonly' | 'invalid-user' | 'unauthorized' | 'invalid-date' | 'invalid-name' | 'invalid-name-is-email' | 'banned' | 'invalid-email' | 'invalid-input' | 'missing-id' | 'not-found'
7 /** 於失敗時包含。 **/
8 reason?: string
9}
10
DELETE /api/v1/comments/:id
Resource: Comment as DELETE /api/v1/comments/:id Credit Cost: 1
此 API 端點提供刪除留言的功能。
注意事項：
- 此 API 可以在需要時即時更新留言小工具（live）。這會將
creditsCost從1提高到2。 - 此 API 會刪除所有子留言。
留言 刪除 cURL 範例
Copy
1
2curl --request DELETE \
3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json'
5
留言 刪除 請求 結構
Copy
1
2interface CommentDeleteQueryParams {
3 tenantId: string
4 API_KEY: string
5 /** 執行更新的使用者。若需要可用來檢查該使用者是否可以刪除該留言。 **/
6 contextUserId?: string
7 /** 是否應對正在檢視具有相同 urlId 的留言小工具實例的使用者即時（live）刪除該留言。NOTE: Doubles credit cost from 1 to 2. **/
8 isLive?: 'true' | 'false'
9}
10
留言 刪除 回應 結構
Copy
1
2
3interface CommentDeleteResponse {
4 status: 'success' | 'failed'
5 /** 失敗時包含。 **/
6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
7 /** 失敗時包含。 **/
8 reason?: string
9}
10
POST /api/v1/comments/:id/flag
Resource: Comment as POST /api/v1/comments/:id/flag Credit Cost: 1
此 API 端點可讓您為特定使用者標記（檢舉）評論。
注意事項：
- 此呼叫必須在使用者上下文中執行。該使用者可以是 FastComments.com 使用者、SSO 使用者或租戶使用者。
- 若已設定標記以隱藏的閾值，當評論被標記達到該次數時，將會即時自動隱藏該評論。
- 在評論被自動取消核准（隱藏）之後，該評論只能由管理員或版主重新核准。取消標記不會使評論重新核准。
評論檢舉 cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/flag?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \
4 --header 'Content-Type: application/json'
5
對於匿名檢舉，我們必須指定一個 anonUserId。這可以是代表匿名會話的 ID，或是一個隨機的 UUID。
這讓我們即使在使用者未登入時也能支援對評論的標記與取消標記。這樣一來，該評論可以被標示為
已標記，當以相同的 anonUserId 取回評論時。
匿名評論檢舉 cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/flag?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \
4 --header 'Content-Type: application/json'
5
評論檢舉請求結構
Copy
1
2interface CommentFlagQueryParams {
3 tenantId: string
4 API_KEY: string
5 userId?: string
6 anonUserId?: string
7}
8
評論檢舉回應結構
Copy
1
2
3interface CommentFlagResponse {
4 status: 'success' | 'failed'
5 /** 失敗時會包含。 **/
6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id'
7 /** 失敗時會包含。 **/
8 reason?: string
9 /** 該評論是否因被標記次數過多而被自動取消核准（隱藏）？ **/
10 wasUnapproved?: boolean;
11}
12
POST /api/v1/comments/:id/un-flag
Resource: Comment as POST /api/v1/comments/:id/un-flag Credit Cost: 1
此 API 端點提供對特定使用者取消標記評論的功能。
Notes:
- 此呼叫必須始終在使用者的上下文中執行。該使用者可以是 FastComments.com User、SSO User，或 Tenant User。
- 當評論被自動取消核可（隱藏）後，該評論只能由管理員或版主重新核可。取消標記不會重新核可該評論。
評論取消標記 cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-flag?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \
4 --header 'Content-Type: application/json'
5
For anonymous flagging, we must specify an anonUserId. This can be an ID that represents the anonymous session, or a random UUID.
匿名評論標記 cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-flag?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \
4 --header 'Content-Type: application/json'
5
評論取消標記請求結構
Copy
1
2interface CommentFlagQueryParams {
3 tenantId: string
4 API_KEY: string
5 userId?: string
6 anonUserId?: string
7}
8
評論取消標記回應結構
Copy
1
2
3interface CommentUnFlagResponse {
4 status: 'success' | 'failed'
5 /** 失敗時包含。 **/
6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id'
7 /** 失敗時包含。 **/
8 reason?: string
9}
10
POST /api/v1/comments/:id/block
Resource: Comment as POST /api/v1/comments/:id/block Credit Cost: 1
此 API 端點提供封鎖撰寫特定評論的使用者的功能。它支援封鎖來自 FastComments.com 使用者、SSO 使用者 和 租戶使用者 的評論。
它支援一個 commentIdsToCheck 主體參數，用來檢查在此操作完成後客戶端上是否有任何其他可能可見的評論應該被封鎖/解除封鎖。
注意：
- 此呼叫必須始終在使用者的上下文中進行。該使用者可以是 FastComments.com 使用者、SSO 使用者，或租戶使用者。
- 請求中的
userId是正在「執行封鎖」的使用者。例如：User A想要封鎖User B。傳入userId=User A以及User B所撰寫的評論 id。 - 完全匿名的評論（沒有使用者 id、沒有電子郵件）無法被封鎖，系統將回傳錯誤。
評論封鎖 cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/block?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \
4 --header 'Content-Type: application/json'
5
若要對匿名使用者進行封鎖，我們必須指定一個 anonUserId。這可以是代表匿名會話的 ID，或是一個隨機的 UUID。
這允許我們在使用者未登入時，透過使用相同的 anonUserId 來擷取評論並支援封鎖評論。
匿名評論封鎖 cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/block?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \
4 --header 'Content-Type: application/json'
5
評論封鎖請求結構
Copy
1
2interface CommentBlockQueryParams {
3 tenantId: string
4 API_KEY: string
5 userId?: string
6 anonUserId?: string
7 commentIdsToCheck?: string[]
8}
9
評論封鎖回應結構
Copy
1
2
3interface CommentBlockResponse {
4 status: 'success' | 'failed'
5 /** 發生錯誤時包含。 **/
6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id' | 'comment-cannot-be-blocked'
7 /** 發生錯誤時包含。 **/
8 reason?: string
9 /** 如果定義了 commentIdsToCheck，則此映射中值為 true 的項目也會被封鎖。 **/
10 commentStatuses?: Record<string, boolean>;
11}
12
POST /api/v1/comments/:id/un-block
Resource: Comment as POST /api/v1/comments/:id/un-block Credit Cost: 1
此 API 端點提供解除對撰寫特定評論之使用者封鎖的功能。它支援解除封鎖由 FastComments.com 使用者、SSO 使用者，以及租戶使用者所撰寫的評論。
它支援一個 commentIdsToCheck 的 body 參數，用來檢查在此操作執行後，客戶端上任何其他可能可見的評論是否應該被封鎖/解除封鎖。
注意：
- 此呼叫必須始終在某個使用者的上下文中進行。該使用者可以是 FastComments.com 使用者、SSO 使用者，或租戶使用者。
- 請求中的
userId指的是正在解除封鎖的那個使用者。例如：User A想要解除封鎖User B。傳入userId=User A以及User B所撰寫的評論 id。 - 完全匿名的評論（沒有使用者 id、沒有 email）無法被封鎖，系統將回傳錯誤。
評論解除封鎖 cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-block?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \
4 --header 'Content-Type: application/json'
5
匿名評論解除封鎖 cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-block?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \
4 --header 'Content-Type: application/json'
5
評論解除封鎖請求結構
Copy
1
2interface CommentUnBlockQueryParams {
3 tenantId: string
4 API_KEY: string
5 userId?: string
6 anonUserId?: string
7 commentIdsToCheck?: string[]
8}
9
評論解除封鎖回應結構
Copy
1
2
3interface CommentUnBlockResponse {
4 status: 'success' | 'failed'
5 /** 失敗時包含。 **/
6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id' | 'comment-cannot-be-blocked'
7 /** 失敗時包含。 **/
8 reason?: string
9 /** 如果定義了 commentIdsToCheck，這個映射中為 true 的條目仍然被封鎖。如果為 false，您可能想要把這些評論對使用者取消隱藏，這樣使用者就不需要重新整理。 **/
10 commentStatuses?: Record<string, boolean>;
11}
12
電子郵件範本結構
一個 EmailTemplate 物件代表租戶的自訂電子郵件範本設定。
系統會透過下列方式選擇要使用的電子郵件範本：
- 其類型識別符，我們稱之為
emailTemplateId。這些是常數。 domain。我們會先嘗試尋找與相關物件（例如Comment）所屬網域相符的範本，若找不到相符者，則會嘗試尋找 domain 為 null 或*的範本。
以下為 EmailTemplate 物件的結構：
電子郵件範本結構
Copy
1
2interface EmailTemplate {
3 id: string
4 tenantId: string
5 emailTemplateId: string
6 displayName: string
7 /** 唯讀 **/
8 createdAt: string
9 /** 唯讀 **/
10 updatedAt: string
11 /** 唯讀 **/
12 updatedByUserId: string
13 /** 範本應該關聯的網域。 **/
14 domain?: string | '*' | null
15 /** 以 EJS 語法的電子郵件範本內容。 **/
16 ejs: string
17 /** 針對每個支援的語系，覆寫翻譯鍵到值的映射。 **/
18 translationOverridesByLocale: Record<string, Record<string, string>>
19 /** 表示範本的渲染上下文的物件。 **/
20 testData: object
21}
22
注意事項
- 您可以從
/definitions端點取得有效的emailTemplateId值。 /definitions端點也包含預設翻譯和測試資料。- 如果結構或測試資料無效，範本將無法儲存。
GET /api/v1/email-templates/:id
Resource: EmailTemplate as GET /api/v1/email-templates/:id Credit Cost: 1
可以透過對應的 id 來擷取單一 EmailTemplate（不是 emailTemplateId）。
以 ID 取得 EmailTemplate 的 cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/email-templates/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
以 ID 取得 EmailTemplate 的請求結構
Copy
1
2interface EmailTemplatesByIdRequestQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
以 ID 取得 EmailTemplate 的回應結構
Copy
1
2interface EmailTemplateResponse {
3 status: 'success' | 'failed'
4 /** 僅在失敗時包含。 **/
5 code?: 'internal' | 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found'
6 /** 僅在失敗時包含。 **/
7 reason?: string
8 emailTemplate?: EmailTemplate | null
9}
10
GET /api/v1/email-templates
Resource: EmailTemplate as GET /api/v1/email-templates Credit Cost: 1
此 API 使用分頁，由 page 查詢參數提供。EmailTemplates 以每頁 100 筆的方式回傳，排序先依 createdAt，再依 id。
EmailTemplate cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/email-templates?tenantId=demo&page=0&API_KEY=DEMO_API_SECRET'
4
EmailTemplate 請求結構
Copy
1
2interface EmailTemplatesRequestQueryParams {
3 tenantId: string
4 API_KEY: string
5 /** 要擷取的頁面，從 0 開始。 **/
6 page: number
7}
8
EmailTemplate 回應結構
Copy
1
2interface EmailTemplatesResponse {
3 status: 'success' | 'failed'
4 /** 失敗時會包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
6 /** 失敗時會包含。 **/
7 reason?: string
8 emailTemplates: EmailTemplate[]
9}
10
PATCH /api/v1/email-templates/:id
Resource: EmailTemplate as PATCH /api/v1/email-templates/:id Credit Cost: 1
此 API 端點允許只指定 id 與要更新的屬性來更新電子郵件範本。
請注意，建立範本時相同的所有驗證也同樣適用，例如：
- 範本必須能正確渲染。每次更新都會檢查此項。
- 同一網域不能有重複的範本（否則其中一個會被靜默忽略）。
EmailTemplate PATCH cURL 範例
Copy
1
2curl --request PATCH \
3 --url 'https://fastcomments.com/api/v1/email-templates/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "displayName": "Some New Name",
7}'
8
EmailTemplate PATCH 請求結構
Copy
1
2interface EmailTemplatePatchQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
EmailTemplate PATCH 回應結構
Copy
1
2
3interface EmailTemplatePatchResponse {
4 status: 'success' | 'failed'
5 /** 失敗時會包含。 **/
6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'not-found' | 'unexpected-param' | 'invalid-email-template-id' | 'unauthorized' | 'domain-invalid' | 'duplicate' | 'does-not-render';
7 /** 失敗時會包含。 **/
8 reason?: string
9 /** 更新後的電子郵件範本。 **/
10 emailTemplate?: EmailTemplate
11}
12
POST /api/v1/email-templates
Resource: EmailTemplate as POST /api/v1/email-templates Credit Cost: 1
此 API 端點提供建立電子郵件範本的功能。
注意事項：
- 相同網域下不能有多個使用相同
emailTemplateId的範本。 - 但你可以同時擁有通配符範本（
domain=*）以及同一emailTemplateId的特定網域範本。 - 只有在你擁有不同網域，或想針對特定情境使用專屬範本（例如測試時將
domain設為localhost）時，才需要指定domain。 - 如果指定
domain，它必須符合某個DomainConfig。若錯誤，會提供可使用的網域清單。 - 範本語法為 EJS，渲染有 500ms 的逾時限制。渲染的 P99 小於 5ms，因此若達到 500ms 表示有問題。
- 要儲存，範本必須能使用你提供的
testData成功渲染。渲染錯誤會彙總並顯示在儀表板（很快也將透過 API 提供）。
新增範本所需的最少資料如下：
最小 EmailTemplate POST cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/email-templates?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "emailTemplateId": "comment-user-mention",
7 "displayName": "I'm a custom template.",
8 "ejs": "This is an @mention notification! My name is <%= comment.commenterName %>."
9}'
10
你可能想為每個網站設定範本，在這種情況下請定義 domain：
EmailTemplate POST cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/email-templates?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "emailTemplateId": "comment-user-mention",
7 "displayName": "I'm a custom template.",
8 "ejs": "This is some email content!",
9 "domain": "somespecificsite.com",
10}'
11
EmailTemplate POST 請求結構
Copy
1
2interface EmailTemplatePostQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
EmailTemplate POST 回應結構
Copy
1
2
3interface EmailTemplatePostResponse {
4 status: 'success' | 'failed'
5 /** 失敗時會包含。 **/
6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'unexpected-param' | 'invalid-email-template-id' | 'domain-invalid' | 'duplicate' | 'does-not-render';
7 /** 失敗時會包含。 **/
8 reason?: string
9 /** 已建立的範本。 **/
10 emailTemplate?: EmailTemplate
11}
12
POST /api/v1/email-templates/render
Resource: EmailTemplate as POST /api/v1/email-templates/render Credit Cost: 1
此 API 端點可用來預覽電子郵件範本。
最小 EmailTemplate 預覽 POST cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/email-templates/render?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "emailTemplateId": "comment-user-mention",
7 "displayName": "I'm a custom template.",
8 "ejs": "This is an @mention notification! My name is <%= comment.commenterName %>."
9}'
10
EmailTemplate POST 請求結構
Copy
1
2interface EmailTemplatePostQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
EmailTemplate POST 回應結構
Copy
1
2
3interface EmailTemplatePostResponse {
4 status: 'success' | 'failed'
5 /** 失敗時包含。 **/
6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'unexpected-param' | 'does-not-render';
7 /** 失敗時包含。 **/
8 reason?: string
9 /** 成功時回傳的渲染後 HTML。 **/
10 html?: string
11}
12
DELETE /api/v1/email-templates/:id
Resource: EmailTemplate as DELETE /api/v1/email-templates/:id Credit Cost: 1
此路由會刪除單一 EmailTemplate（依 id）。
EmailTemplate 刪除 cURL 範例
Copy
1
2curl --request DELETE \
3 --url 'https://fastcomments.com/api/v1/email-templates/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
EmailTemplate 刪除請求結構
Copy
1
2interface EmailTemplateRequestQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
EmailTemplate 刪除回應結構
Copy
1
2interface EmailTemplateDeleteResponse {
3 status: 'success' | 'failed'
4 /** 僅在失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized'
6 /** 僅在失敗時包含。 **/
7 reason?: string
8}
9
主題標籤結構
一個 HashTag 物件代表使用者可以留下的標籤。HashTag 可用於連結到外部的內容或將相關評論串連起來。
HashTag 物件的結構如下：
HashTag 結構
Copy
1
2interface HashTag {
3 /** 應以 "#" 或其他想要的字元開頭。 **/
4 tag: string
5 /** 可選的 URL，hashtag 可指向此 URL。與其透過 hashtag 篩選評論，UI 在點擊時會導向此處。 **/
6 url?: string
7 /** 唯讀 **/
8 createdAt: string
9}
10
注意：
- 在某些 API 端點中，你會看到 hashtag 被用在 URL 中。請記得對值進行 URI 編碼。例如，
#應該表示為%23。 - 其中某些欄位被標示為
READONLY- 這些欄位由 API 回傳，但無法設定。
GET /api/v1/hash-tags
Resource: HashTag as GET /api/v1/hash-tags Credit Cost: 1
此 API 使用分頁，透過 page 查詢參數提供。HashTags 會以每頁 100 筆返回，並依 tag 排序。
HashTag cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/hash-tags?tenantId=demo&page=0&API_KEY=DEMO_API_SECRET'
4
HashTag 請求結構
Copy
1
2interface HashTagsRequestQueryParams {
3 tenantId: string
4 API_KEY: string
5 /** 要取得的頁面，從 0 開始。 **/
6 page: number
7}
8
HashTag 回應結構
Copy
1
2interface HashTagsResponse {
3 status: 'success' | 'failed'
4 /** Included on failure. **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
6 /** Included on failure. **/
7 reason?: string
8 /** 這些主題標籤！ **/
9 hashTags: HashTag[]
10}
11
PATCH /api/v1/hash-tags/:tag
Resource: HashTag as PATCH /api/v1/hash-tags/:tag Credit Cost: 1
此路由提供更新單一個 HashTag 的功能。
HashTag 更新 cURL 範例
Copy
1
2curl --request PATCH \
3 --url 'https://fastcomments.com/api/v1/hash-tags/%23example_hash_tag?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "url": "https://example.com/some-`page`"
7}'
8
HashTag 更新請求結構
Copy
1
2interface HashTagPatchQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
HashTag 更新回應結構
Copy
1
2interface HashTagPatchResponse {
3 status: 'success' | 'failed'
4 /** 於失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist' | 'url-too-long' | 'invalid-tag' | 'already-exists'
6 /** 於失敗時包含。 **/
7 reason?: string
8 hashTag?: HashTag; // 成功時回傳完整更新後的 HashTag。
9}
10
POST /api/v1/hash-tags
Resource: HashTag as POST /api/v1/hash-tags Credit Cost: 1
此路由提供新增單一 HashTag 的功能。
HashTag 建立 cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/hash-tags?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "tag": "#example",
7 "url": "https://example.com/some-page"
8}'
9
HashTag 建立請求結構
Copy
1
2interface HashTagPostQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
HashTag 建立回應結構
Copy
1
2interface HashTagPostResponse {
3 status: 'success' | 'failed'
4 /** 僅在失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist' | 'url-too-long' | 'invalid-tag'
6 /** 僅在失敗時包含。 **/
7 reason?: string
8 hashTag?: HashTag; // 成功時回傳完整建立的 hashtag。
9}
10
POST /api/v1/hash-tags/bulk
Resource: HashTag as POST /api/v1/hash-tags/bulk Credit Cost: 1
此路由允許一次新增最多 100 個 HashTag 物件。
HashTag 批次建立 cURL 範例
Copy
1
2curl --request PATCH \
3 --url 'https://fastcomments.com/api/v1/hash-tags/bulk?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "tags": [
7 {
8 "tag": "#example",
9 "url": "https://example.com/some-page"
10 }
11 ]
12}'
13
HashTag 批次建立請求結構
Copy
1
2interface HashTagPostQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
HashTag 批次建立回應結構
Copy
1
2interface HashTagBulkPostResponse {
3 status: 'success' | 'failed'
4 /** 失敗時會包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist' | 'url-too-long' | 'invalid-tag'
6 /** 失敗時會包含。 **/
7 reason?: string
8 results?: HashTagPostResponse[]; // 我們會為每個提供的標籤回傳一個 HashTagPostResponse 物件的清單。
9}
10
DELETE /api/v1/hash-tags/:tag
Resource: HashTag as DELETE /api/v1/hash-tags/:tag Credit Cost: 1
此路由提供透過所提供的標籤刪除一個 HashTag 使用者。
請注意，除非停用自動 HashTag 建立，否則使用者在留言時提供該標籤時，該標籤可能會被重新建立。
HashTag 刪除 cURL 範例
Copy
1
2curl --request DELETE \
3 --url 'https://fastcomments.com/api/v1/hash-tags/%23example_hash_tag?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
HashTag 刪除請求結構
Copy
1
2interface HashTagDeleteQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
HashTag 刪除回應結構
Copy
1
2interface HashTagDeleteResponse {
3 status: 'success' | 'failed'
4 /** 失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist'
6 /** 失敗時包含。 **/
7 reason?: string
8}
9
版主結構
A Moderator object represents configuration for a moderator.
有三種類型的版主：
- 擁有
isCommentModeratorAdmin標記的管理員使用者。 - 具有
isCommentModeratorAdmin標記的 SSO 使用者。 - 被邀請為版主的一般留言者，或 FastComments.com 的使用者。
Moderator 結構用於表示用例 3 的審核狀態。
如果您想透過 API 邀請某人成為版主，請使用 Moderator API，建立一個 Moderator 並邀請他們。
如果該使用者沒有 FastComments.com 帳號，邀請信將協助他們完成設定。如果他們已經有帳號，他們會被授予對您租戶的審核存取權，且 Moderator 物件的 userId 將更新為指向他們的使用者。您不會有該使用者的 API 存取權，因為在這種情況下該帳號屬於他們自己並由 FastComments.com 管理。
如果您需要完整管理該使用者的帳戶，我們建議使用 SSO，或將他們新增為 租戶使用者，然後再新增一個 Moderator 物件以追蹤他們的統計資料。
Moderator 結構可以用作用例 1 和 2 的統計追蹤機制。建立使用者後，新增一個定義了他們 userId 的 Moderator 物件，他們的統計將會在 留言版主頁面 上被追蹤。
Moderator 物件的結構如下：
Moderator 結構
Copy
1
2interface Moderator {
3 name: string
4 email: string
5 tenantId: string
6 userId?: string|null
7 acceptedInvite?: boolean
8 markReviewedCount?: number
9 deletedCount?: number
10 markedSpamCount?: number
11 approvedCount?: number
12 editedCount?: number
13 bannedCount?: number
14 createdAt: string
15 moderationGroupIds?: string[]|null
16}
17
GET /api/v1/moderators/:id
Resource: Moderator as GET /api/v1/moderators/:id Credit Cost: 1
此路由會依其 id 回傳單一位管理員。
以 ID 取得管理員的 cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/moderators/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
管理員請求結構
Copy
1
2interface ModeratorByIdQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
管理員回應結構
Copy
1
2interface ModeratorByIdResponse {
3 status: 'success' | 'failed'
4 /** 失敗時會包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
6 /** 失敗時會包含。 **/
7 reason?: string
8 moderator?: Moderator
9}
10
GET /api/v1/moderators
Resource: Moderator as GET /api/v1/moderators Credit Cost: 1
此 API 使用分頁，由 skip 查詢參數提供。管理員會以每頁 100 名的方式回傳，依據 createdAt 和 id 排序。
成本基於回傳的管理員數量計算，為每回傳 1 credit per 10 名管理員收費。
管理員 cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/moderators?tenantId=demo&skip=0&API_KEY=DEMO_API_SECRET'
4
管理員 請求 結構
Copy
1
2interface ModeratorsRequestQueryParams {
3 tenantId: string
4 API_KEY: string
5 /** 分頁時要跳過的管理員數量。 **/
6 skip?: number
7}
8
管理員 回應 結構
Copy
1
2interface ModeratorsResponse {
3 status: 'success' | 'failed'
4 /** 僅在失敗時會包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
6 /** 僅在失敗時會包含。 **/
7 reason?: string
8 moderators?: Moderator[]
9}
10
PATCH /api/v1/moderators/:id
Resource: Moderator as PATCH /api/v1/moderators/:id Credit Cost: 1
此 API 端點提供透過 id 更新 Moderator 的功能。
更新 Moderator 有以下限制：
- 更新
Moderator時不得提供下列欄位：acceptedInvitemarkReviewedCountdeletedCountmarkedSpamCountapprovedCounteditedCountbannedCountverificationIdcreatedAt
- 當指定
userId時，該使用者必須存在。 - 當指定
userId時，該使用者必須屬於查詢參數中指定的相同tenantId。 - 在相同租戶中，兩名管理員不得使用相同的
email。 - 您不得變更與
Moderator關聯的tenantId。
管理員 PATCH cURL 範例
Copy
1
2curl --request PATCH \
3 --url 'https://fastcomments.com/api/v1/moderators/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "name": "Some New Name",
7}'
8
管理員 PATCH 請求結構
Copy
1
2interface ModeratorPatchQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
管理員 PATCH 回應結構
Copy
1
2
3interface ModeratorPatchResponse {
4 status: 'success' | 'failed'
5 /** 僅於失敗時包含。 **/
6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'name-required' | 'email-required' | 'unexpected-param' | 'not-found';
7 /** 僅於失敗時包含。 **/
8 reason?: string
9}
10
POST /api/v1/moderators
Resource: Moderator as POST /api/v1/moderators Credit Cost: 1
此路由允許新增單一個 Moderator。
建立 Moderator 有下列限制：
- 必須提供
name和email。userId為選填。 - 建立
Moderator時不得提供下列值：acceptedInvitemarkReviewedCountdeletedCountmarkedSpamCountapprovedCounteditedCountbannedCountverificationIdcreatedAt
- 當指定
userId時，該使用者必須存在。 - 當指定
userId時，他們必須屬於在查詢參數中指定的相同tenantId。 - 同一租戶中不能新增兩位具有相同
email的 moderator。
我們可以為只有電子郵件資訊的使用者建立 Moderator：
透過 Email 建立 Moderator 的 cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/moderators?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "name": "Some Name",
7 "email": "someone@someone.com"
8}'
9
或者，我們可以為屬於我們租戶的使用者建立 Moderator，以追蹤其審核統計資料：
透過租戶使用者建立 Moderator 的 cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/moderators?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "name": "Some Name",
7 "email": "someone@someone.com",
8 "userId": "some-tenant-user-id"
9}'
10
Moderator 建立請求結構
Copy
1
2interface ModeratorPostQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
Moderator 建立回應結構
Copy
1
2interface ModeratorPostResponse {
3 status: 'success' | 'failed'
4 /** 失敗時會包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'name-required' | 'email-required' | 'unexpected-param' | 'not-found'
6 /** 失敗時會包含。 **/
7 reason?: string
8 moderator?: Moderator; // 成功時會回傳完整建立的 Moderator。
9}
10
POST /api/v1/moderators/:id/send-invite
Resource: Moderator as POST /api/v1/moderators/:id/send-invite Credit Cost: 10
此路由提供邀請單一位 Moderator 的功能。
The following restrictions exist to send an invite email to a Moderator:
Moderator必須已經存在。fromName長度不得超過100 characters。
Notes:
- 如果具有該電子郵件的使用者已存在，他們將會被邀請來管理您租戶的評論。
- 如果具有該電子郵件的使用者 不存在，邀請連結會引導他們建立帳戶。
- 邀請將在
30 days後到期。
我們可以為只知道電子郵件的使用者建立 Moderator：
版主邀請 cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/moderators/xyz/send-invite?tenantId=demo&API_KEY=DEMO_API_SECRET&fromName=Bob' \
4 --header 'Content-Type: application/json'
5
This will send an email like Bob at TenantName is inviting you to be a moderator...
版主邀請請求結構
Copy
1
2interface ModeratorSendInviteQueryParams {
3 tenantId: string
4 API_KEY: string
5 /** 寄送給使用者的電子郵件將顯示為由此名稱發出。 **/
6 fromName: string
7}
8
版主邀請回應結構
Copy
1
2interface ModeratorSendInviteResponse {
3 status: 'success' | 'failed'
4 /** 失敗時會包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'not-found | 'from-name-required' | 'from-name-invalid'
6 /** 失敗時會包含。 **/
7 reason?: string
8}
9
DELETE /api/v1/moderators/:id
Resource: Moderator as DELETE /api/v1/moderators/:id Credit Cost: 5
此路由提供依 id 刪除 Moderator 的功能。
Moderator 移除 cURL 範例
Copy
1
2curl --request DELETE \
3 --url 'https://fastcomments.com/api/v1/moderators/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
Moderator 移除請求結構
Copy
1
2interface ModeratorDeleteQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
Moderator 移除回應結構
Copy
1
2interface ModeratorDeleteResponse {
3 status: 'success' | 'failed'
4 /** 僅在失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found'
6 /** 僅在失敗時包含。 **/
7 reason?: string
8}
9
通知計數結構
A NotificationCount 物件表示使用者的未讀通知數量與相關的描述性資訊。
如果沒有未讀通知，該使用者將不會有 NotificationCount。
NotificationCount 物件會自動建立，無法透過 API 建立。它們也會在一年後過期。
您可以透過刪除使用者的 NotificationCount 來清除該使用者的未讀通知數量。
NotificationCount 物件的結構如下：
NotificationCount 結構
Copy
1
2interface NotificationCount {
3 id: string // 使用者 id
4 count: number
5 createdAt: string // 日期字串
6 expireAt: string // 日期字串
7}
8
GET /api/v1/notification-count/:user_id
Resource: NotificationCount as GET /api/v1/notification-count/:user_id Credit Cost: 1
此路由會依使用者 ID 傳回單一 NotificationCount。若使用 SSO，使用者 ID 的格式為 <tenant id>:<user id>。
若沒有未讀通知，將不會有 NotificationCount，因此會收到 404。
此路由與 notifications/count 不同，因為它更快，但不允許篩選。
以 ID 取得 NotificationCount 的 cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/notification-count/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
4# -> {"status":"success","data":{"count":1,"createdAt":"2023-03-06T18:45:01.726Z","expireAt":"2024-03-06T01:25:01.726Z","id":"example"}}
5
NotificationCount 請求結構
Copy
1
2interface NotificationCountGetQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
NotificationCount 回應結構
Copy
1
2interface NotificationCountGetResponse {
3 status: 'success' | 'failed'
4 /** 失敗時會包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'not-found'
6 /** 失敗時會包含。 **/
7 reason?: string
8 data?: NotificationCount
9}
10
DELETE /api/v1/notification-count/:user_id
Resource: NotificationCount as DELETE /api/v1/notification-count/:user_id Credit Cost: 1
此路由會依使用者 ID 刪除單一個 NotificationCount。使用 SSO 時，使用者 ID 的格式為 <tenant id>:<user id>。
這將清除使用者的未讀通知數（留言元件中的紅色鈴鐺會淡出，計數會消失）。
DELETE NotificationCount cURL 範例
Copy
1
2curl --request DELETE \
3 --url 'https://fastcomments.com/api/v1/notification-count/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
4# -> {"status":"success"}
5
NotificationCount 刪除請求結構
Copy
1
2interface NotificationCountDeleteQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
NotificationCount 刪除回應結構
Copy
1
2interface NotificationCountDeleteResponse {
3 status: 'success' | 'failed'
4 /** 失敗時會包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'not-found'
6 /** 失敗時會包含。 **/
7 reason?: string
8}
9
通知結構
A Notification object represents a notification for a user.
Notification objects are created automatically and cannot be created via the API. They also expire after one year.
Notifications cannot be deleted. They can however be updated to set viewed to false, and you can query by viewed.
A user may also opt out of notifications for a specific comment by setting optedOut in the notification to true. You can opt in again by setting it to false.
There are different notification types - check relatedObjectType and type.
The ways notifications are created is quite flexible and can be triggered by many scenarios (see NotificationType).
As of today, the existence of a Notification does not actually imply an email is or should be sent. Rather, the notifications
are used for the notification feed and related integrations.
The structure for the Notification object is as follows:
通知結構
Copy
1
2enum NotificationObjectType {
3 Comment = 0,
4 Profile = 1,
5 Tenant = 2
6}
7
8enum NotificationType {
9 /** 如果有人回覆了你。 **/
10 RepliedToMe = 0,
11 /** 如果有人在你評論之討論串中的任何地方回覆（即使是子留言的子留言）。 **/
12 RepliedTransientChild = 1,
13 /** 如果你的評論被按讚。 **/
14 VotedMyComment = 2,
15 /** 如果在你訂閱的頁面的根層有新評論。 **/
16 SubscriptionReplyRoot = 3,
17 /** 如果有人在你的個人資料上評論。 **/
18 CommentedOnProfile = 4,
19 /** 如果你有私人訊息。 **/
20 DirectMessage = 5,
21 /** TrialLimits 僅適用於租戶用戶。 **/
22 TrialLimits = 6,
23 /** 如果你被 @ 提及。 **/
24 Mentioned = 7
25}
26
27interface Notification {
28 id: string
29 tenantId: string
30 /** With SSO, the user id is in the format `<tenant id>:<user id>`. **/
31 userId?: string
32 /** When working with SSO, you only have to worry about `userId`. **/
33 anonUserId?: string
34 /** urlId is almost always defined. It is only optional for tenant-level notifications, which are infrequent. **/
35 urlId?: string
36 /** URL is cached for quick navigation to the source of the notification. **/
37 url?: string
38 /** Page Title is cached for quick reading of notification source. **/
39 pageTitle?: string
40 relatedObjectType: NotificationObjectType
41 /** For example, comment id. **/
42 relatedObjectId: string
43 viewed: boolean
44 createdAt: string // 日期字串
45 type: NotificationType
46 fromCommentId?: string
47 fromVoteId?: string
48 /** fromUserName and fromUserAvatarSrc are cached here for quick displaying of the notification. They are updated when the user is updated. **/
49 fromUserName: string
50 fromUserId: string
51 fromUserAvatarSrc?: string
52 /** Set this to true to stop getting notifications for this object. **/
53 optedOut?: boolean
54}
55
GET /api/v1/notifications
Resource: Notification as GET /api/v1/notifications Credit Cost: 1
此路由會回傳最多 30 個 Notification 物件，依 createdAt 排序，最新的在前。
你可以以 userId 過濾。使用 SSO 時，使用者 id 的格式為 <tenant id>:<user id>。
使用者未讀通知 cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/notifications?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=SOME_USER_ID&viewed=false'
4
通知請求結構
Copy
1
2interface NotificationsGetQueryParams {
3 tenantId: string
4 API_KEY: string
5 /** 透過跳過記錄進行分頁。 **/
6 skip?: number
7 /** 以使用者過濾。 **/
8 userId?: string
9 /** 以 urlId 過濾。 **/
10 urlId?: string
11 /** 以來源評論過濾。 **/
12 fromCommentId?: string
13 /** 以已讀/未讀 過濾。 **/
14 viewed?: 'true' | 'false'
15 /** 以類型過濾。 **/
16 type?: NotificationType
17}
18
通知回應結構
Copy
1
2interface NotificationsGetResponse {
3 status: 'success' | 'failed'
4 /** 失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
6 /** 失敗時包含。 **/
7 reason?: string
8 notifications?: Notification[]
9}
10
GET /api/v1/notifications/count
Resource: Notification as GET /api/v1/notifications/count Credit Cost: 2
此路由會回傳一個物件，包含在 count 參數下的通知數量。
它比 /notification-count/ 慢且花費雙倍點數，但允許在更多維度上過濾。
您可以使用與 /notifications 端點相同的參數進行過濾，例如 userId。使用 SSO 時，使用者 ID 的格式為 <tenant id>:<user id>。
使用者未讀通知數量 cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/notifications/count?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=SOME_USER_ID&viewed=false'
4
特定頁面使用者未讀通知數量 cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/notifications/count?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=SOME_USER_ID&viewed=false&urlId=some-article-id-or-url'
4
通知數量請求結構
Copy
1
2interface NotificationCountGetQueryParams {
3 tenantId: string
4 API_KEY: string
5 /** 依使用者過濾。 **/
6 userId?: string
7 /** 依 urlId 過濾。 **/
8 urlId?: string
9 /** 依來源留言過濾。 **/
10 fromCommentId?: string
11 /** 依已讀/未讀 過濾。 **/
12 viewed?: 'true' | 'false'
13 /** 依類型過濾。 **/
14 type?: NotificationType
15}
16
通知數量回應結構
Copy
1
2interface NotificationCountGetResponse {
3 status: 'success' | 'failed'
4 /** 失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
6 /** 失敗時包含。 **/
7 reason?: string
8 count?: number
9}
10
PATCH /api/v1/notifications/:id
Resource: Notification as PATCH /api/v1/notifications/:id Credit Cost: 1
此 API 端點提供透過 id 更新 Notification 的功能。
更新 Notification 有以下限制：
- 您只能更新以下欄位：
viewedoptedOut
Notification PATCH cURL 範例
Copy
1
2curl --request PATCH \
3 --url 'https://fastcomments.com/api/v1/notifications/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "viewed": false,
7}'
8
Notification PATCH 請求結構
Copy
1
2interface NotificationPatchQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
Notification PATCH 回應結構
Copy
1
2
3interface NotificationPatchResponse {
4 status: 'success' | 'failed'
5 /** 於失敗時包含。 **/
6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'unauthorized' | 'not-found';
7 /** 於失敗時包含。 **/
8 reason?: string
9}
10
頁面結構
一個 Page 物件代表許多評論可能屬於的頁面。這種關係是由 urlId 定義的。
Page 儲存像是頁面標題、評論數量及 urlId 等資訊。
Page 物件的結構如下：
頁面結構
Copy
1
2interface Page {
3 id: string
4 urlId: string
5 url: string
6 title?: string
7 createdAt: string
8 commentCount: number
9 rootCommentCount: number
10 /** 將此設為 null 表示所有 SSO 使用者都可以看到該頁面。空清單表示該頁面對所有使用者關閉。 **/
11 accessibleByGroupIds?: string[] | null
12 /** 此頁面是否已關閉以接受新評論？ **/
13 isClosed?: boolean
14}
15
GET /api/v1/pages
Resource: Page as GET /api/v1/pages Credit Cost: 10
你目前只能擷取與你的帳戶相關的所有頁面（或透過 /by-url-id 擷取單一頁面）。如果你想要更細緻的搜尋，請聯絡我們。
頁面 cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/pages?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
頁面請求結構
Copy
1
2interface PagesRequestQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
頁面回應結構
Copy
1
2interface PagesResponse {
3 status: 'success' | 'failed'
4 /** 僅在失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
6 /** 僅在失敗時包含。 **/
7 reason?: string
8 pages: Page[]
9}
10
有用提示
The Comment API requires a urlId. You can call the Pages API first, to see what the urlId values available to you
look like.
GET /api/v1/pages/by-url-id
Resource: Page as GET /api/v1/pages/by-url-id Credit Cost: 1
個別頁面可以透過其對應的 urlId 來擷取。這對於查詢頁面標題或留言數量很有幫助。
以 URL ID 取得頁面 cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/pages/by-url-id?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=example-id-or-url'
4
以 URL ID 取得頁面請求結構
Copy
1
2interface PagesRequestQueryParams {
3 tenantId: string
4 API_KEY: string
5 urlId: string
6}
7
以 URL ID 取得頁面回應結構
Copy
1
2interface PagesResponse {
3 status: 'success' | 'failed'
4 /** 失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id'
6 /** 失敗時包含。 **/
7 reason?: string
8 page?: Page[] | null
9}
10
有用提示
請記得將像 urlId 這類值進行 URI 編碼。
PATCH /api/v1/pages/:id
Resource: Page as PATCH /api/v1/pages/:id Credit Cost: 1
此路由提供更新單一 Page 的功能。相應的評論也會被更新。
頁面更新 cURL 範例
Copy
1
2curl --request PATCH \
3 --url 'https://fastcomments.com/api/v1/pages/my-page-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "url": "https://example.com/some-page"
7}'
8
頁面更新請求結構
Copy
1
2interface PagePatchQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
頁面更新回應結構
Copy
1
2interface PagePatchResponse {
3 status: 'success' | 'failed'
4 /** 失敗時會包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'missing-id' | 'page-does-not-exist' | 'empty-request' | 'internal' | 'invalid-input' | 'invalid-title' | 'extra-params' | 'accessible-by-group-ids-not-array' | 'too-many-group-ids' | 'group-id-too-large'
6 /** 失敗時會包含。 **/
7 reason?: string
8 user?: Page; // 成功時會回傳完整更新後的頁面。
9}
10
注意
某些 Page 物件中的參數會自動更新。這些包括計數與 title 屬性。計數無法透過 API 更新，因為它們是計算出的值。頁面的 title 可以透過 API 設定，但如果在具有相同 urlId 且頁面標題不同的頁面上使用評論小工具，該標題將會被覆蓋。
POST /api/v1/pages
Resource: Page as POST /api/v1/pages Credit Cost: 1
此 API 端點提供建立頁面的功能。
一個常見的使用情境是存取控制。
Notes:
- If you've commented on a comment thread, or called the API to create a
Comment, you've already created aPageobject! You can try fetching it via the/by-url-idPageroute, passing in the sameurlIdpassed to the comment widget. - The
Pagestructure contains some 計算得出 values. Currently, these arecommentCountandrootCommentCount. They are populated automatically and cannot be set by the API. Attempting to do so will cause the API to return an error.
頁面 POST cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/pages?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "title": "Test Page",
7 "url": "some0-url",
8 "urlId": "page2",
9 "accessibleByGroupIds": ["SOME_GROUP_ID"]
10}'
11
頁面 POST 請求結構
Copy
1
2interface PagePostQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
頁面 POST 回應結構
Copy
1
2
3interface PagePostResponse {
4 status: 'success' | 'failed'
5 /** 僅在失敗時包含。 **/
6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-request' | 'internal' | 'invalid-input' | 'invalid-title' | 'extra-params' | 'accessible-by-group-ids-not-array' | 'too-many-group-ids' | 'group-id-too-large';
7 /** 僅在失敗時包含。 **/
8 reason?: string
9 /** 已建立的頁面。 **/
10 page?: Page
11}
12
DELETE /api/v1/pages/:id
Resource: Page as DELETE /api/v1/pages/:id Credit Cost: 1
此路由提供依 id 刪除單一頁面的功能。
請注意，對具有相同 urlId 的頁面的評論元件進行互動，將會無縫地重新建立該 Page。
頁面刪除 cURL 範例
Copy
1
2curl --request DELETE \
3 --url 'https://fastcomments.com/api/v1/pages/some-page-id?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
頁面刪除請求結構
Copy
1
2interface PageDeleteQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
頁面刪除回應結構
Copy
1
2interface PageDeleteResponse {
3 status: 'success' | 'failed'
4 /** 失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'page-does-not-exist'
6 /** 失敗時包含。 **/
7 reason?: string
8}
9
待處理 Webhook 事件結構
A PendingWebhookEvent object represents a queued webhook event that is pending.
PendingWebhookEvent objects are created automatically and cannot be manually created via the API. They also expire after one year.
They can be deleted which removes the task from the queue.
There are different event types - check eventType (OutboundSyncEventType) and type (OutboundSyncType).
A common use case for this API is to implement custom monitoring. You may want to call the /count endpoint periodically
to poll the outstanding count for given filters.
The structure for the PendingWebhookEvent object is as follows:
PendingWebhookEvent 結構
Copy
1
2enum OutboundSyncEventType {
3 Create: 0,
4 Delete: 1,
5 Update: 2
6}
7
8enum OutboundSyncType {
9 /** WordPress 專用的同步任務。 **/
10 WP: 0,
11 Webhook: 1
12}
13
14interface PendingWebhookEvent {
15 id: string
16 /** 與事件相關聯的評論 id。 **/
17 commentId: string
18 /** 事件發生時對應的評論物件。我們從 2023 年 11 月開始加入這些資訊。 **/
19 comment: Comment
20 /** 可能與評論相關聯的外部 id。 **/
21 externalId: string | null
22 createdAt: Date
23 tenantId: string
24 attemptCount: number
25 /** 在第一次嘗試前以及每次失敗後設定。 **/
26 nextAttemptAt: Date
27 /** 表示這是建立、刪除或更新事件之一... **/
28 eventType: OutboundSyncEventType
29 /** 要執行的同步類型（WordPress、呼叫 API 等）。 **/
30 type: OutboundSyncType
31 /** 與評論相符合的網域。我們使用此網域來選擇 API 金鑰。 **/
32 domain: string
33 /** 最近發生的錯誤。此欄位未具型別，為對發生內容的「傾印」。通常包含一個具有 statusCode、body 與 headers 地圖的物件。 **/
34 lastError: object | null
35}
36
GET /api/v1/pending-webhook-events
Resource: PendingWebhookEvent as GET /api/v1/pending-webhook-events Credit Cost: 2
此路由會回傳位於 pendingWebhookEvents 參數下的待處理 webhook 事件列表。
此 API 使用分頁，由 skip 參數提供。PendingWebhookEvents 以每頁 100 筆回傳，依 createdAt 由新到舊排序。
PendingWebhookEvent cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/pending-webhook-events?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
PendingWebhookEvent 請求結構
Copy
1
2interface PendingWebhookEventsGetQueryParams {
3 tenantId: string
4 API_KEY: string
5 commentId?: string
6 externalId?: string
7 eventType?: OutboundSyncEventType
8 type?: OutboundSyncType
9 domain?: string
10 /** 查詢嘗試次數大於指定數量的事件。 **/
11 attemptCountGT?: number
12}
13
PendingWebhookEvent 回應結構
Copy
1
2interface PendingWebhookEventsGetResponse {
3 status: 'success' | 'failed'
4 /** 失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
6 /** 失敗時包含。 **/
7 reason?: string
8 pendingWebhookEvents?: PendingWebhookEvent[]
9}
10
GET /api/v1/pending-webhook-events/count
Resource: PendingWebhookEvent as GET /api/v1/pending-webhook-events/count Credit Cost: 2
此路由會回傳一個物件，其在 count 參數中包含待處理的 webhook 事件數量。
您可以使用與 /pending-webhook-events 端點相同的參數進行篩選
PendingWebhookEvent 計數 cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/pending-webhook-events/count?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
PendingWebhookEvent 計數請求結構
Copy
1
2interface PendingWebhookEventsCountQueryParams {
3 tenantId: string
4 API_KEY: string
5 commentId?: string
6 externalId?: string
7 eventType?: OutboundSyncEventType
8 type?: OutboundSyncType
9 domain?: string
10 /** 查詢嘗試次數大於指定數字的事件。 **/
11 attemptCountGT?: number
12}
13
PendingWebhookEvent 計數回應結構
Copy
1
2interface PendingWebhookEventsCountResponse {
3 status: 'success' | 'failed'
4 /** 失敗時會包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
6 /** 失敗時會包含。 **/
7 reason?: string
8 count?: number
9}
10
DELETE /api/v1/pending-webhook-events/:id
Resource: PendingWebhookEvent as DELETE /api/v1/pending-webhook-events/:id Credit Cost: 1
此路由允許刪除單一的 PendingWebhookEvent。
如果需要大量刪除，請先呼叫帶分頁的 GET API，然後依序呼叫此 API。
DELETE PendingWebhookEvent cURL 範例
Copy
1
2curl --request DELETE \
3 --url 'https://fastcomments.com/api/v1/pending-webhook-events/some-id?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
刪除 PendingWebhookEvent 請求結構
Copy
1
2interface PendingWebhookEventDeleteQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
刪除 PendingWebhookEvent 回應結構
Copy
1
2interface PendingWebhookEventDeleteResponse {
3 status: 'success' | 'failed'
4 /** 失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
6 /** 失敗時包含。 **/
7 reason?: string
8}
9
SSO 使用者結構
FastComments 提供易於使用的 SSO 解決方案。使用基於 HMAC 的整合更新使用者資訊，就像讓使用者載入帶有更新載荷的頁面一樣簡單。
不過，您可能會希望在該流程之外管理使用者，以改善應用程式的一致性。
SSO 使用者 API 提供一種對我們稱為 SSOUser 的物件進行 CRUD 的方式。這些物件不同於一般的 Users，並為了型別安全而分開保存。
SSOUser 物件的結構如下：
SSOUser 結構
Copy
1
2interface SSOUser {
3 id: string
4 username: string
5 email?: string
6 websiteUrl?: string
7 signUpDate: number
8 createdFromUrlId?: string
9 loginCount?: number
10 avatarSrc?: string
11 optedInNotifications?: boolean
12 optedInSubscriptionNotifications?: boolean
13 displayLabel?: string
14 displayName?: string
15 isAccountOwner?: boolean // 管理員權限 - 有此標記的 SSO 使用者會以 SSO 管理員身分計費（與一般 SSO 使用者分開）
16 isAdminAdmin?: boolean // 管理員權限 - 有此標記的 SSO 使用者會以 SSO 管理員身分計費（與一般 SSO 使用者分開）
17 isCommentModeratorAdmin?: boolean // 版主權限 - 有此標記的 SSO 使用者會以 SSO 版主身分計費（與一般 SSO 使用者分開）
18 /** 如果為 null，則不會將存取控制套用到該使用者。如果為空列表，該使用者將無法看到任何頁面或在 @ 提及其他使用者。 **/
19 groupIds?: string[] | null
20 createdFromSimpleSSO?: boolean
21 /** 不要讓其他使用者在其個人檔案上看到此使用者的活動（包括留言）。預設為 true，以預設提供更安全的個人檔案。 **/
22 isProfileActivityPrivate?: boolean
23 /** 不要讓其他使用者在該使用者的個人檔案上留言，或看到現有的個人檔案留言。預設為 false。 **/
24 isProfileCommentsPrivate?: boolean
25 /** 不要讓其他使用者傳送直接訊息給此使用者。預設為 false。 **/
26 isProfileDMDisabled?: boolean
27 karma?: number
28 /** 使用者徽章的可選設定。 **/
29 badgeConfig?: {
30 /** 分配給使用者的徽章 ID 陣列。最多限制為 30 個徽章。順序會被保留。 **/
31 badgeIds: string[]
32 /** 如果為 true，將用提供的徽章取代所有現有顯示的徽章。如果為 false 或省略，則會將提供的徽章新增到現有徽章。 **/
33 override?: boolean
34 /** 如果為 true，當使用者登入時會從租戶設定更新徽章顯示屬性。 **/
35 update?: boolean
36 }
37}
38
SSO 使用者計費
SSO 使用者會根據其權限標記以不同方式計費：
- 一般 SSO 使用者：沒有管理員或版主權限的使用者將以一般 SSO 使用者計費
- SSO 管理員：具有
isAccountOwner或isAdminAdmin標記的使用者會被另外計費為 SSO 管理員（與一般租戶管理員相同費率） - SSO 版主：具有
isCommentModeratorAdmin標記的使用者會被另外計費為 SSO 版主（與一般版主相同費率）
重要：為了避免重複計費，系統會自動根據電子郵件地址將 SSO 使用者與一般租戶使用者和版主去重。如果 SSO 使用者與一般租戶使用者或版主具有相同的電子郵件，則不會被重複計費。
存取控制
使用者可以被分到不同群組。這就是 groupIds 欄位的用途，且為選用。
@ 提及
預設情況下，當輸入 @ 字元時，@mentions 會使用 username 來搜尋其他 SSO 使用者。如果使用 displayName，當 displayName 有匹配時，符合 username 的結果將被忽略，而 @mention 的搜尋結果會使用 displayName。
訂閱
在 FastComments 中，使用者可以透過在留言小工具中點擊鈴鐺圖示並選擇訂閱來訂閱頁面。
對於一般使用者，我們會根據他們的通知設定發送通知電子郵件。
對於 SSO 使用者，我們為了向後相容將此行為拆分。只有當您將 optedInSubscriptionNotifications 設為 true 時，使用者才會收到這些額外的訂閱通知電子郵件。
徽章
您可以使用 badgeConfig 屬性為 SSO 使用者指定徽章。徽章是在留言中顯示於使用者名稱旁的視覺指標。
badgeIds- 指派給使用者的徽章 ID 陣列。這些必須是您在 FastComments 帳戶中建立的有效徽章 ID。最多限制為 30 個徽章。override- 如果為 true，留言上所有現有顯示的徽章將被提供的徽章取代。如果為 false 或省略，提供的徽章將會新增到現有徽章中。update- 如果為 true，當使用者登入時徽章的顯示屬性會從租戶設定更新。
GET /api/v1/sso-users
Resource: SSOUser as GET /api/v1/sso-users Credit Cost: 10
此路由會以每頁 100 名的分頁方式回傳 SSO 使用者。分頁由 skip 參數提供。使用者依其 signUpDate 與 id 排序。
SSOUsers cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/sso-users?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
SSOUsers 請求結構
Copy
1
2interface SSOUsersRequestQueryParams {
3 tenantId: string
4 API_KEY: string
5 skip?: number
6}
7
SSOUsers 回應結構
Copy
1
2interface SSOUsersResponse {
3 status: 'success' | 'failed'
4 /** 僅在失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
6 /** 僅在失敗時包含。 **/
7 reason?: string
8 users: SSOUser[]
9}
10
GET /api/v1/sso-users/by-id/:id
Resource: SSOUser as GET /api/v1/sso-users/by-id/:id Credit Cost: 1
此路由會依據其 id 回傳單一 SSO 使用者。
依 ID 取得 SSOUser 的 cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/sso-users/by-id/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
SSOUser 請求結構
Copy
1
2interface SSOUserRequestByIdQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
SSOUser 回應結構
Copy
1
2interface SSOUserByIdResponse {
3 status: 'success' | 'failed'
4 /** 失敗時會包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'user-does-not-exist'
6 /** 失敗時會包含。 **/
7 reason?: string
8 user: SSOUser
9}
10
GET /api/v1/sso-users/by-email/:email
Resource: SSOUser as GET /api/v1/sso-users/by-email/:email Credit Cost: 1
此路由會依使用者的電子郵件回傳單一 SSO 使用者。
依電子郵件取得 SSO 使用者 cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/sso-users/by-email/someone@somewhere.com?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
SSOUser 請求結構
Copy
1
2interface SSOUserRequestByEmailQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
SSOUser 回應結構
Copy
1
2interface SSOUserByEmailResponse {
3 status: 'success' | 'failed'
4 /** 僅於失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-email' | 'user-does-not-exist'
6 /** 僅於失敗時包含。 **/
7 reason?: string
8 user: SSOUser
9}
10
PATCH /api/v1/sso-users/:id
Resource: SSOUser as PATCH /api/v1/sso-users/:id Credit Cost: 1
此路由提供更新單一 SSO 使用者的功能。
SSOUser 更新 cURL 範例
Copy
1
2curl --request PATCH \
3 --url 'https://fastcomments.com/api/v1/sso-users/my-user-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "username": "notfordperfect"
7}'
8
SSOUser 更新請求結構
Copy
1
2interface SSOUserPatchQueryParams {
3 tenantId: string
4 API_KEY: string
5 /** 當電子郵件或使用者名稱被更改時，您可以將此設定為 true 以同時更新該使用者的評論。這會使信用成本增加一倍。 **/
6 updateComments: 'true' | 'false'
7}
8
SSOUser 更新回應結構
Copy
1
2interface SSOUserPatchResponse {
3 status: 'success' | 'failed'
4 /** 在失敗時會包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-does-not-exist'
6 /** 在失敗時會包含。 **/
7 reason?: string
8 user?: SSOUser; // 在成功時會回傳完整更新後的使用者。
9}
10
POST /api/v1/sso-users
Resource: SSOUser as POST /api/v1/sso-users Credit Cost: 1
此路由用於建立單一 SSO 使用者。
嘗試建立兩個具有相同 ID 的使用者會導致錯誤。
SSOUser 建立 cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/sso-users?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "id": "my-user-id",
7 "username": "fordperfect",
8 "displayName": "Ford Perfect",
9 "email": "fordperfect@galaxy.com",
10 "groupIds": ["some-optional-group-id"]
11}'
12
在此範例中我們為存取控制指定了 groupIds，但這是可選的。
SSOUser 建立請求結構
Copy
1
2interface SSOUserPostQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
SSOUser 建立回應結構
Copy
1
2interface SSOUserPostResponse {
3 status: 'success' | 'failed'
4 /** 失敗時會包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-exists'
6 /** 失敗時會包含。 **/
7 reason?: string
8 user?: SSOUser; // 成功時會回傳建立的使用者。
9}
10
整合注意事項
透過 API 傳遞的資料可以透過傳遞不同的 SSO User HMAC payload 來覆寫。例如，如果 您透過 API 設定了一個 username，但在頁面載入時透過 SSO 流程傳遞了不同的 username，我們會自動更新 他們的 username。
除非您明確指定或將其設為 null（不是 undefined），否則我們不會在此流程中更新使用者參數。
PUT /api/v1/sso-users/:id
Resource: SSOUser as PUT /api/v1/sso-users Credit Cost: 1
此路由提供更新單一 SSO 使用者的功能。
SSOUser 更新 cURL 範例
Copy
1
2curl --request PUT \
3 --url 'https://fastcomments.com/api/v1/sso-users/my-user-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "username": "fordperfect",
7 "displayName": "Ford Perfect",
8 "email": "fordperfect@galaxy.com",
9 "groupIds": ["some-optional-group-id"]
10}'
11
在此範例中，我們為存取控制指定了 groupIds，但這是可選的。
SSOUser 更新 請求 結構
Copy
1
2interface SSOUserPutQueryParams {
3 tenantId: string
4 API_KEY: string
5 /** 當 email 或 username 被更改時，你可以將此設為 true 以同時更新使用者的留言。這將使點數成本加倍。 **/
6 updateComments: 'true' | 'false'
7}
8
SSOUser 更新 回應 結構
Copy
1
2interface SSOUserPutResponse {
3 status: 'success' | 'failed'
4 /** 失敗時會包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-exists'
6 /** 失敗時會包含。 **/
7 reason?: string
8 user?: SSOUser; // 成功時回傳更新後的使用者。
9}
10
DELETE /api/v1/sso-users/:id
Resource: SSOUser as DELETE /api/v1/sso-users/:id Credit Cost: 1
此路由可透過使用者的 id 刪除單一 SSO 使用者。
請注意，若再次以該使用者的 payload 載入留言小工具，系統會無縫地重新建立該使用者。
可透過查詢參數 deleteComments 刪除此使用者的留言。若此參數為 true，請注意：
- 該使用者的所有留言將會即時刪除。
- 所有的 子留言（現為孤兒留言）將依據各留言所屬頁面的設定，被刪除或匿名化。例如，若討論串刪除模式為 "anonymize"，則回覆會保留，而該使用者的留言會被匿名化。此行為僅適用於
commentDeleteMode為Remove（預設值）時。 creditsCost會變為2。
匿名化留言
您可以保留該使用者的留言，但透過將 commentDeleteMode=1 將其匿名化。
若使用者的留言被匿名化，則下列欄位會被設為 null：
- commenterName
- commenterEmail
- avatarSrc
- userId
- anonUserId
- mentions
- badgesisDeleted 與 isDeletedUser 將被設為 true。
在渲染時，留言小工具會在使用者名稱處使用 DELETED_USER_PLACEHOLDER（預設："[deleted]"），並在留言內容處使用 DELETED_CONTENT_PLACEHOLDER。可透過 Widget Customization UI 自訂這些內容。
範例
SSOUser 移除 cURL 範例
Copy
1
2curl --request DELETE \
3 --url 'https://fastcomments.com/api/v1/sso-users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
SSOUser 移除請求結構
Copy
1
2enum SSOUserCommentDeleteMode {
3 Remove = 0, // 預設值
4 Anonymize = 1
5}
6
7interface SSOUsersDeleteQueryParams {
8 tenantId: string
9 API_KEY: string
10 /** 您可以將此設為 true 以同時刪除此使用者的留言。這會使點數成本加倍。 **/
11 deleteComments?: 'true' | 'false'
12 /** 您可以依需求設置此值以決定如何處理該使用者的留言。 **/
13 commentDeleteMode?: SSOUserCommentDeleteMode
14}
15
SSOUser 移除回應結構
Copy
1
2interface SSOUsersResponse {
3 status: 'success' | 'failed'
4 /** 失敗時會包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'user-does-not-exist'
6 /** 失敗時會包含。 **/
7 reason?: string
8 user?: SSOUser; // 成功時會回傳被移除的使用者。
9}
10
訂閱結構
一個 Subscription 物件代表使用者的訂閱。
Subscription 物件會在使用者在評論小工具中點擊通知鈴鐺並點選 "訂閱此頁面" 時建立。
也可以透過 API 建立訂閱。
擁有 Subscription 物件會在與該 Subscription 相關聯的頁面
根層留下新留言時，會產生 Notification 物件並發送電子郵件。
是否發送電子郵件取決於使用者類型。對於一般使用者，這取決於 optedInNotifications。對於 SSO 使用者，則取決於 optedInSubscriptionNotifications。請注意，有些應用程式可能沒有可由網頁存取的頁面概念，在這種情況下，只需將 urlId 設為
您要訂閱的項目的 id（與傳遞給評論小工具的 urlId 值相同）。
以下為 Subscription 物件的結構：
訂閱結構
Copy
1
2interface Subscription {
3 id: string
4 tenantId: string
5 /** 使用 SSO 時，使用者 id 的格式為 `<tenant id>:<user id>`。 **/
6 userId: string
7 anonUserId?: string
8 urlId: string
9 url?: string
10 pageTitle?: string
11 createdAt: string // 日期字串
12}
13
GET /api/v1/subscriptions/:id
Resource: Subscription as GET /api/v1/subscriptions Credit Cost: 1
此路由會回傳最多 30 個 Subscription 物件，依 createdAt 排序，最新的在前。
你可以以 userId 過濾。使用 SSO 時，使用者 id 的格式為 <tenant id>:<user id>。
取得使用者訂閱 cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/subscriptions?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=SOME_USER_ID'
4
Subscriptions 請求結構
Copy
1
2interface SubscriptionsGetQueryParams {
3 tenantId: string
4 API_KEY: string
5 /** 透過跳過紀錄進行分頁。 **/
6 skip?: number
7 /** 以使用者過濾。 **/
8 userId?: string
9}
10
Subscriptions 回應結構
Copy
1
2interface SubscriptionsGetResponse {
3 status: 'success' | 'failed'
4 /** 在失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
6 /** 在失敗時包含。 **/
7 reason?: string
8 subscriptions?: Subscription[]
9}
10
POST /api/v1/subscriptions
Resource: Subscription as POST /api/v1/subscriptions Credit Cost: 1
此 API 端點提供建立 Subscription 的功能。請注意，每位使用者每個頁面只能有一個訂閱，因為多個訂閱是多餘的，且嘗試為同一使用者在同一頁面建立多於一個訂閱會導致錯誤。
建立訂閱時，當在被訂閱的 urlId 根節點留下新留言（當留言的 parentId 為 null）時，將會建立 Notification 物件。
Subscription POST cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/subscriptions?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "userId": "tenantId:test-user-id",
7 "urlId": "some-page-id-or-url",
8 "url": "https://example.com/page",
9 "pageTitle": "Some Example Page!"
10}'
11
Subscription POST 請求結構
Copy
1
2interface SubscriptionPostQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
Subscription POST 回應結構
Copy
1
2
3interface SubscriptionPostResponse {
4 status: 'success' | 'failed'
5 /** 僅在失敗時包含。 **/
6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'unauthorized' | 'not-found';
7 /** 僅在失敗時包含。 **/
8 reason?: string
9}
10
DELETE /api/v1/subscriptions/:id
Resource: Subscription as DELETE /api/v1/subscriptions Credit Cost: 1
此路由會透過 id 刪除單一 Subscription 物件。
刪除訂閱 cURL 範例
Copy
1
2curl --request DELETE \
3 --url 'https://fastcomments.com/api/v1/subscriptions/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
刪除訂閱請求結構
Copy
1
2interface SubscriptionsDeleteQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
刪除訂閱回應結構
Copy
1
2interface SubscriptionDeleteResponse {
3 status: 'success' | 'failed'
4 /** 失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
6 /** 失敗時包含。 **/
7 reason?: string
8}
9
租戶每日使用量結構
A TenantDailyUsage object represents the usage for a tenant on a given day. If there was no activity for a given tenant on a given
day, that day will not have a TenantDailyUsage object.
The TenantDailyUsage object is not real time and may be minutes behind actual usage.
The structure for the TenantDailyUsage object is as follows:
TenantDailyUsage 結構
Copy
1
2export interface TenantDailyUsage {
3 yearNumber: number
4 monthNumber: number
5 dayNumber: number
6 commentFetchCount?: number
7 commentCreateCount?: number
8 conversationCreateCount?: number
9 voteCount?: number
10 accountCreatedCount?: number
11 userMentionSearch?: number
12 hashTagSearch?: number
13 gifSearchTrending?: number
14 gifSearch?: number
15 apiCreditsUsed?: number
16 createdAt: string
17 billed: boolean
18 /** 計費時忽略。 **/
19 ignored: boolean
20}
21
GET /api/v1/tenant-daily-usage
Resource: TenantDailyUsage as GET /api/v1/tenant-daily-usage Credit Cost: 1
此路由允許按年份、月份和日期搜尋租戶的使用情況。最多可回傳 365 個物件，費用為每 10 個物件 1 個 API 點數。
回應物件依建立日期排序（最舊的在前）。
TenantDailyUsage 搜尋 cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/tenant-daily-usage?tenantId=demo&API_KEY=DEMO_API_SECRET&yearNumber=2022&monthNumber=2&dayNumber=10'
4
TenantDailyUsage 請求結構
Copy
1
2interface TenantDailyUsageQueryParams {
3 tenantId: string
4 API_KEY: string
5 /** 基於 UTC。 **/
6 yearNumber?: number
7 /** 從零開始。基於 UTC。 **/
8 monthNumber?: number
9 /** 從 1 開始。基於 UTC。 **/
10 dayNumber?: number
11}
12
TenantDailyUsage 回應結構
Copy
1
2interface TenantDailyUsageResponse {
3 status: 'success' | 'failed'
4 /** 失敗時會包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
6 /** 失敗時會包含。 **/
7 reason?: string
8 tenantDailyUsages: TenantDailyUsage[]
9}
10
租戶結構
The Tenant 定義 FastComments.com 的客戶。具有白標存取權的租戶可以透過 API 建立這些租戶。白標租戶無法建立其他白標租戶（僅允許一層巢狀）。
Tenant 物件的結構如下：
租戶結構
Copy
1
2export enum SiteType {
3 Unknown = 0,
4 WordPress = 1
5}
6
7/** 這也可以透過 DomainConfig API 處理。 **/
8export interface TenantDomainConfig {
9 domain: string
10 emailFromName?: string
11 emailFromEmail?: string
12 createdAt?: string,
13 siteType?: FastCommentsSiteType, // 你可能想要使用 Unknown
14 logoSrc?: string, // 原始圖片路徑
15 logoSrc100px?: string, // 為縮圖調整大小
16 footerUnsubscribeURL?: string,
17 emailHeaders?: Record<string, string>,
18 disableUnsubscribeLinks?: boolean,
19 dkim?: {
20 domainName: string,
21 keySelector: string,
22 privateKey: string
23 }
24}
25
26export interface TenantBillingInfo {
27 name: string
28 address: string
29 city: string
30 state: string
31 zip: string
32 country: string
33}
34
35export enum TenantPaymentFrequency {
36 Monthly = 0,
37 Annually = 1
38}
39
40export interface Tenant {
41 id: string
42 name: string
43 email?: string
44 signUpDate: number; // number 是因為「歷史」原因
45 packageId?: string | null
46 paymentFrequency?: TenantPaymentFrequency
47 billingInfoValid?: boolean
48 billingHandledExternally?: boolean
49 createdBy?: string
50 isSetup?: boolean
51 domainConfiguration: FastCommentsAPITenantDomainConfig[]
52 billingInfo?: FastCommentsAPITenantBillingInfo
53 stripeCustomerId?: string
54 stripeSubscriptionId?: string
55 stripePlanId?: string
56 enableProfanityFilter?: boolean
57 enableSpamFilter?: boolean
58 lastBillingIssueReminderDate?: string
59 removeUnverifiedComments?: boolean
60 unverifiedCommentsTTLms?: number
61 commentsRequireApproval?: boolean
62 autoApproveCommentOnVerification?: boolean
63 sendProfaneToSpam?: boolean
64 /** @readonly - 根據 packageId 計算。 **/
65 hasFlexPricing?: boolean
66 /** @readonly **/
67 flexLastBilledAmount?: number
68 /** @readonly - 根據 packageId 計算。 **/
69 hasAuditing?: boolean
70 /** 你可以在租戶上儲存鍵值對，並用於查詢。鍵不能包含 "." 或 "$"，或長於 100 個字元。值不得超過 2k 字元。 **/
71 meta?: Record<string, string | null>
72}
73
GET /api/v1/tenants/:id
Resource: Tenant as GET /api/v1/tenants/:id Credit Cost: 1
此路由會依 id 回傳單一 Tenant。
以 ID 取得 Tenant 的 cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/tenants/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
Tenant 請求結構
Copy
1
2interface TenantByIdQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
Tenant 回應結構
Copy
1
2interface TenantByIdResponse {
3 status: 'success' | 'failed'
4 /** 失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'unauthorized'
6 /** 失敗時包含。 **/
7 reason?: string
8 tenant?: Tenant
9}
10
GET /api/v1/tenants
Resource: Tenant as GET /api/v1/tenants Credit Cost: 1
此 API 回傳由您的租戶所管理的租戶。
分頁由 skip 查詢參數提供。租戶以每頁 100 筆回傳，依照 signUpDate 與 id 排序。
費用依回傳的租戶數量計算，每回傳 10 位租戶收取 1 credit。
Tenant cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/tenants?tenantId=demo&skip=0&API_KEY=DEMO_API_SECRET'
4
您可以在 Tenant 物件上定義 meta 參數並查詢符合條件的租戶。例如，對於鍵 someKey 與 meta 值 some-value，我們可以建立一個包含該鍵/值對的 JSON 物件，然後將其 URI 編碼作為查詢參數來進行篩選：
Tenant 以 meta 查詢 cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/tenants?tenantId=demo&skip=0&API_KEY=DEMO_API_SECRET&meta=%7B%22someKey%22%3A%22some-value%22%7D'
4
Tenant 請求結構
Copy
1
2interface TenantsRequestQueryParams {
3 tenantId: string
4 API_KEY: string
5 /** 用於分頁要跳過的租戶數量。 **/
6 skip?: number
7 /** 以 meta 參數過濾。 **/
8 meta?: string
9}
10
Tenant 回應結構
Copy
1
2interface TenantsResponse {
3 status: 'success' | 'failed'
4 /** 失敗時會包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
6 /** 失敗時會包含。 **/
7 reason?: string
8 tenants?: Tenant[]
9}
10
POST /api/v1/tenants
Resource: Tenant as POST /api/v1/tenants Credit Cost: 1
此路由提供新增單一個 Tenant 的功能。
建立 Tenant 有以下限制：
- 必須提供
name。 - 必須提供
domainConfiguration。 - 建立
Tenant時不得提供下列值：hasFlexPricinglastBillingIssueReminderDateflexLastBilledAmount
signUpDate不得為未來時間。name長度不得超過200 characters。email長度不得超過300 characters。email必須在所有 FastComments.com 的租戶中保持唯一。- 若父租戶未定義有效的
TenantPackage，則不得建立租戶。- 如果您的租戶是透過 FastComments.com 建立的，這通常不會是問題。
- 您不得建立超過套件中
maxWhiteLabeledTenants定義的租戶數量。 - 您必須指定
tenantId查詢參數，此參數為啟用白牌（white labeling）的parent tenant的 id。
我們只需少數參數即可建立 Tenant：
建立 Tenant 的 cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/tenants?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "name": "Some Name",
7 "email": "someone@someone.com",
8 "domainConfiguration": [ { "domain": "somedomain.com" } ]
9}'
10
Tenant 建立請求結構
Copy
1
2interface TenantPostQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
Tenant 建立回應結構
Copy
1
2interface TenantPostResponse {
3 status: 'success' | 'failed'
4 /** 失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' | 'unexpected-param' | 'sign-up-date-in-future' | 'payment-frequency-invalid' | 'cannot-change-payment-frequency' | 'name-invalid' | 'email-invalid' | 'email-taken' | 'no-package' | 'invalid-package' | 'unauthorized' | 'tenant-limit-reached' | 'cannot-move-tenant' | 'cannot-change-package' | 'invalid-billing-info'
6 /** 失敗時包含。 **/
7 reason?: string
8 tenant?: Tenant; // 成功時會回傳完整的已建立租戶。
9}
10
PATCH /api/v1/tenants/:id
Resource: Tenant as PATCH /api/v1/tenants/:id Credit Cost: 1
此 API 端點提供依 id 更新 Tenant 的功能。
更新 Tenant 有下列限制：
- 下列值不得更新：
hasFlexPricinglastBillingIssueReminderDateflexLastBilledAmountmanagedByTenantId
signUpDate不能是未來的時間。name的長度不得超過200 characters。email的長度不得超過300 characters。email必須在所有 FastComments.com 的租戶中唯一。- 當將
billingInfoValid設為true時，必須在同一請求中提供billingInfo。 - 您不得更新與您自己的租戶關聯的
packageId。 - 您不得更新與您自己的租戶關聯的
paymentFrequency。
租戶 PATCH cURL 範例
Copy
1
2curl --request PATCH \
3 --url 'https://fastcomments.com/api/v1/tenants/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "name": "Some New Name",
7}'
8
租戶 PATCH 請求結構
Copy
1
2interface TenantPatchQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
租戶 PATCH 回應結構
Copy
1
2
3interface TenantPatchResponse {
4 status: 'success' | 'failed'
5 /** 失敗時包含。 **/
6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' | 'unexpected-param' | 'sign-up-date-in-future' | 'payment-frequency-invalid' | 'cannot-change-payment-frequency' | 'name-invalid' | 'email-invalid' | 'email-taken' | 'no-package' | 'invalid-package' | 'unauthorized' | 'tenant-limit-reached' | 'cannot-move-tenant' | 'cannot-change-package' | 'invalid-billing-info';
7 /** 失敗時包含。 **/
8 reason?: string
9}
10
DELETE /api/v1/tenants/:id
Resource: Tenant as DELETE /api/v1/tenants/:id Credit Cost: 1,000
此路由依據 id 刪除一個 Tenant 以及所有相關資料（使用者、留言等）。
移除租戶時有下列限制：
- 該租戶必須是您自己的，或是您管理的白標租戶。
sure查詢參數必須設定為true。
租戶移除 cURL 範例
Copy
1
2curl --request DELETE \
3 --url 'https://fastcomments.com/api/v1/tenants/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
租戶移除請求結構
Copy
1
2interface TenantDeleteQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
租戶移除回應結構
Copy
1
2interface TenantDeleteResponse {
3 status: 'success' | 'failed'
4 /** 失敗時會包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized' | 'unsure'
6 /** 失敗時會包含。 **/
7 reason?: string
8}
9
租戶方案結構
The TenantPackage 定義可供 Tenant 使用的方案資訊。租戶可能有多個可用方案，但在任何時間點僅能有一個被使用。
A Tenant 在其 packageId 指向有效的 TenantPackage 前，無法用於任何產品。
有兩種類型的 TenantPackage 物件：
- 固定定價方案 - 當
hasFlexPricing為 false。 - 彈性定價 - 當
hasFlexPricing為 true。
在兩種情況下，帳戶使用該方案時都會定義限制，然而在彈性定價（Flex）下，租戶會被收取基本費用外加其實際使用量，使用量由 flex* 參數定義。
租戶可以擁有多個租戶方案，並可從 帳單資訊頁面. 自行變更方案。
如果您將自行為租戶處理帳務，您仍然需要為每個租戶定義一個方案以規定其限制。只要在 Tenant 上將 billingHandledExternally 設為 true，他們就無法自行變更帳務資訊或啟用中的方案。
您不得為子租戶建立高於父租戶限制的方案。
TenantPackage 物件的結構如下：
TenantPackage 結構
Copy
1
2export interface TenantPackage {
3 id: string
4 name: string
5 tenantId: string
6 createdAt: string
7 monthlyCostUSD: number
8 yearlyCostUSD: number
9 monthlyStripePlanId?: string
10 yearlyStripePlanId?: string
11 maxMonthlyPageLoads: number
12 maxMonthlyAPICredits: number
13 maxMonthlyComments: number
14 maxConcurrentUsers: number
15 maxTenantUsers: number
16 maxSSOUsers: number
17 maxModerators: number
18 maxDomains: number
19 maxWhiteLabeledTenants: number
20 hasWhiteLabeling: boolean
21 hasDebranding: boolean
22 forWhoText: string
23 featureTaglines: string[]
24 hasAuditing: boolean
25 hasFlexPricing: boolean
26 flexPageLoadCostCents?: null
27 flexPageLoadUnit?: null
28 flexCommentCostCents?: null
29 flexCommentUnit?: null
30 flexSSOUserCostCents?: null // 每位一般 SSO 使用者的費用（不含管理者/版主權限）
31 flexSSOUserUnit?: null
32 flexAPICreditCostCents?: null
33 flexAPICreditUnit?: null
34 flexModeratorCostCents?: null
35 flexModeratorUnit?: null
36 flexAdminCostCents?: null
37 flexAdminUnit?: null
38 flexDomainCostCents?: null
39 flexDomainUnit?: null
40 flexSSOAdminCostCents?: null // 具有管理員權限的 SSO 使用者費用（isAccountOwner 或 isAdminAdmin 標記）
41 flexSSOAdminUnit?: null
42 flexSSOModeratorCostCents?: null // 具有版主權限的 SSO 使用者費用（isCommentModeratorAdmin 標記）
43 flexSSOModeratorUnit?: null
44 flexMinimumCostCents?: null
45}
46
GET /api/v1/tenant-packages/:id
Resource: TenantPackage as GET /api/v1/tenant-packages/:id Credit Cost: 1
此路由會根據 id 回傳單一 Tenant Package。
TenantPackage 以 ID 的 cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/tenant-packages/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
TenantPackage 請求結構
Copy
1
2interface TenantPackageByIdQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
TenantPackage 回應結構
Copy
1
2interface TenantPackageByIdResponse {
3 status: 'success' | 'failed'
4 /** 僅在失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
6 /** 僅在失敗時包含。 **/
7 reason?: string
8 tenantPackage: TenantPackage
9}
10
GET /api/v1/tenant-packages
Resource: TenantPackage as GET /api/v1/tenant-packages Credit Cost: 1
此 API 使用分頁，透過 skip 查詢參數提供。TenantPackages 以每頁 100 筆回傳，依 createdAt 與 id 排序。
費用依回傳的 TenantPackages 數量計算，成本為 1 credit per 10 回傳的 TenantPackages。
TenantPackage cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/tenant-packages?tenantId=demo&skip=0&API_KEY=DEMO_API_SECRET'
4
TenantPackage 請求結構
Copy
1
2interface TenantPackagesRequestQueryParams {
3 tenantId: string
4 API_KEY: string
5 /** 分頁時要跳過的 tenant packages 數量。 **/
6 skip?: number
7}
8
TenantPackage 回應結構
Copy
1
2interface TenantPackagesResponse {
3 status: 'success' | 'failed'
4 /** 僅於失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
6 /** 僅於失敗時包含。 **/
7 reason?: string
8 tenantPackages?: TenantPackage[]
9}
10
POST /api/v1/tenant-packages
Resource: TenantPackage as POST /api/v1/tenant-packages Credit Cost: 1
此路由允許新增單一個 TenantPackage。
建立 TenantPackage 有下列限制：
- 下列參數為必填：
nametenantIdmonthlyCostUSD- 可為 null。yearlyCostUSD- 可為 null。maxMonthlyPageLoadsmaxMonthlyAPICreditsmaxMonthlyCommentsmaxConcurrentUsersmaxTenantUsersmaxSSOUsersmaxModeratorsmaxDomainshasDebrandingforWhoTextfeatureTaglineshasFlexPricing- 若為 true，則所有flex*參數皆為必填。
name的長度不得超過50 characters。forWhoText的每一項不得超過200 characters。featureTaglines的每一項不得超過100 characters。TenantPackage必須比父租戶「更小」。例如，所有max*參數的值都必須低於父租戶。- 白標租戶最多可有 五個套件。
- 僅具有白標存取權的租戶可以建立
TenantPackage。 - 你不能向自己的租戶新增套件。 :)
我們可以依下列方式建立 TenantPackage：
TenantPackage 透過 Email 建立 cURL 範例
Copy
1
2curl --request PATCH \
3 --url 'https://fastcomments.com/api/v1/tenant-packages?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "name": "Default Package",
7 "tenantId": "some-child-tenant-id",
8 "monthlyCostUSD": null,
9 "yearlyCostUSD": null,
10 "maxMonthlyPageLoads": 50000,
11 "maxMonthlyAPICredits": 50000,
12 "maxMonthlyComments": 50000,
13 "maxConcurrentUsers": 50000,
14 "maxTenantUsers": 10,
15 "maxSSOUsers": 50000,
16 "maxModerators": 100,
17 "maxDomains": 3,
18 "hasWhiteLabeling": false,
19 "hasDebranding": true,
20 "forWhoText": "For Everyone",
21 "featureTaglines": [
22 "Some Tag",
23 "Some Other Tag"
24 ],
25 "hasFlexPricing": true,
26 "flexPageLoadCostCents": 100,
27 "flexPageLoadUnit": 100000,
28 "flexCommentCostCents": 100,
29 "flexCommentUnit": 100000,
30 "flexSSOUserCostCents": 100,
31 "flexSSOUserUnit": 1000,
32 "flexAPICreditCostCents": 100,
33 "flexAPICreditUnit": 50000,
34 "flexModeratorCostCents": 500,
35 "flexModeratorUnit": 1,
36 "flexAdminCostCents": 1000,
37 "flexAdminUnit": 1,
38 "flexDomainCostCents": 1000,
39 "flexDomainUnit": 1,
40 "flexMinimumCostCents": 99
41}'
42
TenantPackage 建立請求結構
Copy
1
2interface TenantPackagePostQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
TenantPackage 建立回應結構
Copy
1
2interface TenantPackagePostResponse {
3 status: 'success' | 'failed'
4 /** 失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' 'white-labeling-not-allowed' | 'name-too-long' | 'for-who-text-too-long' | 'feature-tag-lines-too-long' | 'no-package' | 'invalid-package' | 'unauthorized' | 'child-tenant-too-large' | 'flex-param-missing' | 'unexpected-flex-param' | 'package-limit-reached' | 'flex-param-missing' | 'unexpected-flex-param'
6 /** 失敗時包含。 **/
7 reason?: string
8 tenantPackage?: TenantPackage; // 成功時會回傳完整建立的 TenantPackage。
9}
10
PATCH /api/v1/tenant-packages/:id
Resource: TenantPackage as PATCH /api/v1/tenant-packages/:id Credit Cost: 1
此 API 端點可用於透過 id 更新 TenantPackage。
更新 TenantPackage 有下列限制：
- 如果您將
hasFlexPricing設為 true，則同一請求中必須包含所有flex*參數。 name可能不得超過50 characters。- 每個
forWhoText項目可能不得超過200 characters。 - 每個
featureTaglines項目可能不得超過100 characters。 TenantPackage必須比父租戶「小」。例如，所有的max*參數必須比父租戶的值更低。- 您不得變更與
TenantPackage關聯的tenantId。
TenantPackage PATCH cURL 範例
Copy
1
2curl --request PATCH \
3 --url 'https://fastcomments.com/api/v1/tenant-packages/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "name": "Some New Name",
7}'
8
TenantPackage PATCH 請求結構
Copy
1
2interface TenantPackagePatchQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
TenantPackage PATCH 回應結構
Copy
1
2
3interface TenantPackagePatchResponse {
4 status: 'success' | 'failed'
5 /** 於失敗時包含。 **/
6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' | 'white-labeling-not-allowed' | 'name-too-long' | 'for-who-text-too-long' | 'feature-tag-lines-too-long' | 'no-package' | 'invalid-package' | 'unauthorized' | 'child-tenant-too-large' | 'flex-param-missing' | 'unexpected-flex-param' | 'package-limit-reached' | 'flex-param-missing' | 'unexpected-flex-param';
7 /** 於失敗時包含。 **/
8 reason?: string
9}
10
DELETE /api/v1/tenant-packages/:id
Resource: TenantPackage as DELETE /api/v1/tenant-packages/:id Credit Cost: 5
此路由提供依 id 刪除 TenantPackage 的功能。
您無法移除正在使用中的 TenantPackage（若租戶的 packageId 指向該套件）。請先更新該 Tenant。
TenantPackage 刪除 cURL 範例
Copy
1
2curl --request DELETE \
3 --url 'https://fastcomments.com/api/v1/tenant-packages/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
TenantPackage 刪除請求結構
Copy
1
2interface TenantPackageDeleteQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
TenantPackage 刪除回應結構
Copy
1
2interface TenantPackageDeleteResponse {
3 status: 'success' | 'failed'
4 /** 失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized' | 'package-in-use'
6 /** 失敗時包含。 **/
7 reason?: string
8}
9
租戶使用者結構
TenantUser 定義了一個由特定租戶管理的 User。他們的帳戶完全由所屬的租戶控制，且可以透過 UI 或 API 更新或刪除。
租戶使用者可以是擁有全部權限並可存取該 Tenant 的管理者，或僅限於特定權限以
管理留言、存取 API 金鑰等。
The structure for theTenantUserobject is as follows: (Wait, original had backticks around whole sentence? Actually original was: The structure for the TenantUser object is as follows:)
TenantUser 物件的結構如下：
TenantUser 結構
Copy
1
2/** 這是用於通知。 **/
3export enum UserDigestEmailFrequency {
4 Disabled = -1,
5 Daily = 0,
6 Weekly = 1,
7 Monthly = 2
8}
9
10export interface TenantUser {
11 id: string
12 tenantId: string
13 username: string
14 /** 例如留言者的部落格連結。 **/
15 websiteUrl?: string
16 email: string
17 signUpDate: number
18 createdFromUrlId: string
19 createdFromTenantId: string
20 verified: boolean
21 loginCount: number
22 optedInNotifications: boolean
23 optedInTenantNotifications: boolean
24 hideAccountCode: boolean
25 avatarSrc?: string
26 /** 此使用者是否會接收來自留言者的求助請求？ **/
27 isHelpRequestAdmin: boolean
28 isAccountOwner: boolean
29 isAdminAdmin: boolean
30 isBillingAdmin: boolean
31 isAnalyticsAdmin: boolean
32 isCustomizationAdmin: boolean
33 isManageDataAdmin: boolean
34 isCommentModeratorAdmin: boolean
35 isAPIAdmin: boolean
36 moderatorIds: string[]
37 locale: FastCommentsLocale
38 digestEmailFrequency: UserDigestEmailFrequency
39 lastLoginDate: string
40 displayLabel?: string
41 karma?: number
42}
43
GET /api/v1/tenant-users/:id
Resource: TenantUser as GET /api/v1/tenant-users/:id Credit Cost: 1
此路由會根據 id 回傳單一 TenantUser。
以 ID 取得 TenantUser 的 cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/tenant-users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
TenantUser 請求結構
Copy
1
2interface TenantUserByIdQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
TenantUser 回應結構
Copy
1
2interface TenantUserByIdResponse {
3 status: 'success' | 'failed'
4 /** 在失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'unauthorized'
6 /** 在失敗時包含。 **/
7 reason?: string
8 tenantUser?: TenantUser
9}
10
GET /api/v1/tenant-users
Resource: TenantUser as GET /api/v1/tenant-users Credit Cost: 1
此 API 使用分頁機制，由 skip 查詢參數提供。TenantUsers 以每頁 100 筆回傳，排序依序為 signUpDate、username 與 id。
費用依回傳的租戶使用者數量計算，花費為 1 credit per 10（每 10 位租戶使用者）。
TenantUser cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/tenant-users?tenantId=demo&page=0&API_KEY=DEMO_API_SECRET'
4
TenantUser 請求結構
Copy
1
2interface TenantUsersRequestQueryParams {
3 tenantId: string
4 API_KEY: string
5 /** 分頁時要跳過的租戶使用者數量。 **/
6 skip?: number
7}
8
TenantUser 回應結構
Copy
1
2interface TenantUsersResponse {
3 status: 'success' | 'failed'
4 /** 失敗時會包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
6 /** 失敗時會包含。 **/
7 reason?: string
8 tenantUsers?: TenantUser[]
9}
10
POST /api/v1/tenant-users
Resource: TenantUser as POST /api/v1/tenant-users Credit Cost: 1
此路由提供新增單一 TenantUser 的功能。
建立 TenantUser 有下列限制：
username為必填。email為必填。signUpDate不能是未來的時間。locale必須位於 支援的語系 列表中。username必須在整個 FastComments.com 中唯一。如果這成為問題，我們建議改用 SSO。email必須在整個 FastComments.com 中唯一。如果這成為問題，我們建議改用 SSO。- 您不得建立超過套件中
maxTenantUsers定義的租戶使用者數量。
我們可依下列方式建立 TenantUser
TenantUser 建立 cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/tenants?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "username": "Some Name",
7 "email": "someone@someone.com"
8}'
9
TenantUser 建立請求結構
Copy
1
2interface TenantUserPostQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
TenantUser 建立回應結構
Copy
1
2interface TenantUserPostResponse {
3 status: 'success' | 'failed'
4 /** 失敗時會包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'username-required' | 'email-required' | 'sign-up-date-in-future' | 'unsupported-locale' | 'unauthorized' | 'username-taken' | 'email-taken' | 'tenant-user-limit-reached'
6 /** 失敗時會包含。 **/
7 reason?: string
8 tenantUser?: TenantUser; // 成功時回傳完整建立的租戶使用者。
9}
10
POST /api/v1/tenant-users/:id/send-login-link
Resource: TenantUser as POST /api/v1/tenant-users/:id/send-login-link Credit Cost: 10
此路由提供向單一 TenantUser 發送登入連結的功能。
在批量建立使用者且不需指示他們如何登入 FastComments.com 時非常有用。此操作會向他們發送一個可於 30 days 後過期的 "magic link" 用以登入。
發送登入連結給 TenantUser 時有下列限制：
- The
TenantUsermust already exist. - 您必須能管理該
TenantUser所屬的Tenant。
我們可以依下列方式向 TenantUser 發送登入連結：
TenantUser 登入連結 cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/tenant-users/xyz/send-login-link?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json'
5
這將會寄出像 Bob at TenantName is inviting you to be a moderator... 的電子郵件
TenantUser 登入連結請求結構
Copy
1
2interface TenantUserPostQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
TenantUser 登入連結回應結構
Copy
1
2interface TenantUserPostResponse {
3 status: 'success' | 'failed'
4 /** 在失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'not-found'
6 /** 在失敗時包含。 **/
7 reason?: string
8}
9
PATCH /api/v1/tenant-users/:id
Resource: TenantUser as PATCH /api/v1/tenant-users/:id Credit Cost: 1
此路由提供更新單一 TenantUser 的功能。
更新 TenantUser 有下列限制：
signUpDate不能設定為未來時間。locale必須位於 支援的語系 列表中。username必須在整個 FastComments.com 中唯一。如果這成為問題，我們建議改為使用 SSO。email必須在整個 FastComments.com 中唯一。如果這成為問題，我們建議改為使用 SSO。- 您無法更新使用者的
tenantId。
我們可以建立一個 TenantUser 如下
TenantUser 更新 cURL 範例
Copy
1
2curl --request PATCH \
3 --url 'https://fastcomments.com/api/v1/tenant-users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "username": "Some Name",
7 "email": "someone@someone.com"
8}'
9
TenantUser 更新請求結構
Copy
1
2interface TenantUserPatchQueryParams {
3 tenantId: string
4 API_KEY: string
5 /** 當 email 或 username 被更改時，您可以將此設定為 true 以同時更新該使用者的評論。這會使點數成本加倍。 **/
6 updateComments: 'true' | 'false'
7}
8
TenantUser 更新回應結構
Copy
1
2interface TenantUserPatchResponse {
3 status: 'success' | 'failed'
4 /** Included on failure. **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'sign-up-date-in-future' | 'unsupported-locale' | 'unauthorized' | 'username-taken' | 'email-taken' | 'unauthorized' | 'no-package' | 'invalid-package' | 'tenant-user-limit-reached' | 'user-does-not-exist'
6 /** 失敗時包含。 **/
7 reason?: string
8}
9
DELETE /api/v1/tenant-users/:id
Resource: TenantUser as DELETE /api/v1/tenant-users/:id Credit Cost: 5
此路由提供依 id 刪除 TenantUser 的功能。
可透過 deleteComments 查詢參數刪除使用者的評論。請注意若此值為 true：
- 該使用者的所有評論將會即時刪除。
- 所有 child（現為孤兒）的評論將依各評論所屬頁面的設定被刪除或匿名化。例如若執行緒刪除模式為 "anonymize"，則回覆會保留，使用者的評論會被匿名化。此行為僅適用於
commentDeleteMode為Remove（預設值）時。 creditsCost會變為2。
匿名化的評論
您可以保留使用者的評論，但透過設定 commentDeleteMode=1 來將其匿名化。
若使用者的評論被匿名化，則下列欄位會被設為 null：
- commenterName
- commenterEmail
- avatarSrc
- userId
- anonUserId
- mentions
- badgesisDeleted 及 isDeletedUser 會被設為 true。
在渲染時，評論元件會使用 DELETED_USER_PLACEHOLDER（預設："[deleted]"）作為使用者名稱，並使用 DELETED_CONTENT_PLACEHOLDER 作為評論內容。這些可透過 Widget 自訂 UI 來自訂化。
範例
TenantUser 刪除 cURL 範例
Copy
1
2curl --request DELETE \
3 --url 'https://fastcomments.com/api/v1/tenant-users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
TenantUser 刪除請求結構
Copy
1
2enum TenantUserCommentDeleteMode {
3 Remove = 0, // 預設
4 Anonymize = 1
5}
6
7interface TenantUserDeleteQueryParams {
8 tenantId: string
9 API_KEY: string
10 /** 您可以將此設為 true 來同時刪除使用者的評論。這會使點數成本加倍。 **/
11 deleteComments?: 'true' | 'false'
12 /** 您可以依需求設定以決定如何處理使用者的評論。 **/
13 commentDeleteMode?: TenantUserCommentDeleteMode
14}
15
TenantUser 刪除回應結構
Copy
1
2interface TenantUserDeleteResponse {
3 status: 'success' | 'failed'
4 /** 於失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized'
6 /** 於失敗時包含。 **/
7 reason?: string
8}
9
使用者結構
User is an object that represents a most-common denominator of all users.
Keep in mind that at FastComments we have a bunch of different use cases for users:
- 安全 SSO
- 簡易 SSO
- 租戶使用者（例如：管理者）
- 留言者
This API is for 留言者 and users created via 簡易 SSO. Basically, any user created
through your site can be accessed via this API. Tenant Users can also be fetched this way, but you'll get more information by interacting with the /tenant-users/ API.
For Secure SSO please use the /sso-users/ API.
You cannot update these types of users. They created their account through your site, so we provide some basic read-only access, but
you cannot make changes. If you want to have this type of flow - you need to setup Secure SSO.
The structure for the User object is as follows:
使用者結構
Copy
1
2export interface User {
3 /** 這也是在評論物件上用作 userId 的 id。 **/
4 id: string
5 username: string
6 /** 例如：留言者部落格的連結。 **/
7 websiteUrl?: string
8 email: string
9 signUpDate: number
10 createdFromUrlId: string
11 createdFromTenantId: string
12 avatarSrc?: string
13 locale: FastCommentsLocale
14 displayLabel?: string
15 karma?: number
16}
17
GET /api/v1/users/:id
Resource: User as GET /api/v1/users/:id Credit Cost: 1
此路由會根據 id 回傳單一使用者。
按 ID 取得使用者 cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
使用者請求結構
Copy
1
2interface UserByIdQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
使用者回應結構
Copy
1
2interface UserByIdResponse {
3 status: 'success' | 'failed'
4 /** 失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'unauthorized'
6 /** 失敗時包含。 **/
7 reason?: string
8 user?: User
9}
10
投票結構
一個 Vote 物件代表使用者所留下的投票。
留言與投票之間的關係由 commentId 定義。
Vote 物件的結構如下：
Vote 結構
Copy
1
2interface Vote {
3 id: string
4 urlId: string
5 commentId: string
6 userId: string
7 direction: 1 | -1
8 createdAt: string
9}
10
GET /api/v1/votes
Resource: Vote as GET /api/v1/votes Credit Cost: 10
投票必須透過 urlId 取得。
投票類型
有三種類型的投票：
- 已認證的投票，會套用到相對應的留言。您可以透過此 API 建立這些投票。
- 待驗證的已認證投票，因此尚未套用到留言。當使用者使用 FastComments.com login to vote 機制時，會建立這些投票。
- 匿名投票，會套用到相對應的留言。這些會在匿名留言時一併建立。
為了減少混淆，API 會將這些投票分別回傳在不同的列表中。
Votes cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/votes?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=test'
4
投票請求結構
Copy
1
2interface VotesRequestQueryParams {
3 tenantId: string
4 API_KEY: string
5 urlId: string
6}
7
投票回應結構
Copy
1
2interface VotesResponse {
3 status: 'success' | 'failed'
4 /** 失敗時會包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id'
6 /** 失敗時會包含。 **/
7 reason?: string
8 /** 經授權、已驗證的投票，會套用到其相對應的留言。 **/
9 appliedAuthorizedVotes: Vote[]
10 /** 匿名投票，會套用到其相對應的留言。 **/
11 appliedAnonymousVotes: Vote[]
12 /** 待驗證的投票，尚未套用到其相對應的留言。 **/
13 pendingVotes: Vote[]
14}
15
匿名投票注意事項
請注意：透過此 API 建立的匿名投票會出現在 appliedAuthorizedVotes 列表中。由於這些是使用 API 金鑰透過 API 建立的，因此被視為已授權。
appliedAnonymousVotes 結構則用於未提供電子郵件、API 金鑰等的投票。
GET /api/v1/votes/for-user
Resource: Vote as GET /api/v1/votes/for-user Credit Cost: 1
允許取得使用者在指定 urlId 上留下的投票。接受一個 userId，該值可以是任何 FastComments.com 的使用者或 SSO User。
若你想顯示某使用者是否對留言投過票，這會很有用。當取得留言時，只要同時為該使用者對相同的 urlId 呼叫此 API 即可。
如果你使用匿名投票，則應傳入 anonUserId。
用戶投票 cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/votes/for-user?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=test&userId=some-user-id'
4
匿名用戶投票 cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/votes/for-user?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=test&anonUserId=some-user-id'
4
請注意匿名投票會出現在 appliedAuthorizedVotes 列表中。它們被視為已授權，因為是透過具有 API 金鑰的 API 建立的。
用戶投票請求結構
Copy
1
2interface VotesForUserRequestQueryParams {
3 tenantId: string
4 API_KEY: string
5 urlId: string
6 userId?: string
7 anonUserId?: string
8}
9
用戶投票回應結構
Copy
1
2interface VotesForUserResponse {
3 status: 'success' | 'failed'
4 /** 僅在失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'invalid-user-id'
6 /** 僅在失敗時包含。 **/
7 reason?: string
8 /** 已授權、已驗證的投票，已套用到其對應的留言。 **/
9 appliedAuthorizedVotes: Vote[]
10 /** 待驗證的投票，尚未套用到其對應的留言。 **/
11 pendingVotes: Vote[]
12}
13
POST /api/v1/votes
Resource: Vote as POST /api/v1/votes Credit Cost: 1
此路由提供新增單一已授權 Vote 的功能。投票可以是 up (+1) 或 down (-1)。
建立 Vote 的 cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/votes?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=user-id&commentId=comment-id&direction=up' \
4 --header 'Content-Type: application/json'
5
建立匿名 Vote 的 cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/votes?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-randomly-generated-identifier&commentId=comment-id&direction=up' \
4 --header 'Content-Type: application/json'
5
Vote 建立請求結構
Copy
1
2interface VotePostQueryParams {
3 tenantId: string
4 API_KEY: string
5 userId?: string
6 anonUserId?: string
7 commentId: string
8 direction: 'up' | 'down'
9}
10
Vote 建立回應結構
Copy
1
2interface VotePostResponse {
3 status: 'success' | 'failed'
4 /** 僅於失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-user-id' | 'invalid-user-id' | 'invalid-comment-id' | 'invalid-direction' | 'duplicate' | 'voting-disabled'
6 /** 僅於失敗時包含。 **/
7 reason?: string
8 voteId?: string
9}
10
建立匿名投票
可透過在查詢參數中設定 anonUserId 而非 userId 來建立匿名投票。
此 id 不必對應到任何地方的使用者物件（因此為匿名）。它只是一個識別符， 用於識別會話，讓你能在相同會話中再次取得投票，以檢查某則留言是否已被投票。
如果你沒有像 FastComments 那樣的「匿名會話」，你可以將其設為隨機 ID，例如 UUID（但我們偏好較短的識別符以節省空間）。
其他備註
- 此 API 遵從租戶層級的設定。例如，若你對特定頁面停用投票，並嘗試透過 API 建立投票，會以錯誤代碼
voting-disabled失敗。 - 預設此 API 為上線狀態。
- 此 API 會更新對應
Comment的votes。
DELETE /api/v1/votes/:id
Resource: Vote as DELETE /api/v1/votes/:id Credit Cost: 1
此路由提供刪除單一 Vote 的功能。
Vote 刪除 cURL 範例
Copy
1
2curl --request DELETE \
3 --url 'https://fastcomments.com/api/v1/votes/some-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json'
5
Vote 刪除請求結構
Copy
1
2interface VoteDeleteQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
Vote 刪除回應結構
Copy
1
2interface VoteDeleteResponse {
3 status: 'success' | 'failed'
4 /** 失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id'
6 /** 失敗時包含。 **/
7 reason?: string
8}
9
Notes:
- This API obeys tenant-level settings. For example, if you disable voting for a given page, and you attempt to create a vote via the API, it will fail with error code
voting-disabled. - This API is live by default.
- This API will update the
votesof the correspondingComment.
網域設定結構
A DomainConfig object represents configuration for a domain for a tenant.
The structure for the DomainConfig object is as follows:
網域設定結構
Copy
1
2interface DomainConfig {
3 /** 一個網域，不是 URL，例如 "fastcomments.com" 或 "www.example.com"。如果想限制到子網域，可以包含子網域。最多 1000 個字元。 **/
4 domain: string
5 /** 寄信時使用的寄件人名稱。 **/
6 emailFromName?: string
7 /** 寄信時使用的寄件人電子郵件。請確保 SPF 設定允許 mail.fastcomments.com 以此屬性所使用的網域發送郵件。 **/
8 emailFromEmail?: string
9 /** 唯讀。物件建立時間。 **/
10 createdAt: string
11 /** 與此網域相關的 logo。用於電子郵件。請使用 HTTPS。 **/
12 logoSrc?: string
13 /** 與此網域相關的較小 logo。請使用 HTTPS。 **/
14 logoSrc100px?: string
15 /** 僅 SSO。用於每封寄出的電子郵件頁尾的 URL。支援 "[userId]" 變數。 **/
16 footerUnsubscribeURL?: string
17 /** 僅 SSO。用於每封寄出電子郵件的標頭。例如可用來設定退訂相關的標頭以改善投遞率。此記錄中的 List-Unsubscribe 條目（如果存在）支援 "[userId]" 變數。 **/
18 emailHeaders?: Record<string, string>
19 /** 停用所有退訂連結。不建議，可能會降低投遞率。 **/
20 disableUnsubscribeLinks?: boolean
21 /** DKIM 設定。 **/
22 dkim?: DomainConfigDKIM
23}
24
DKIM 設定結構
Copy
1
2interface DomainConfigDKIM {
3 /** DKIM 紀錄中的網域名稱。 **/
4 domainName: string
5 /** 要使用的 DKIM 金鑰選擇器。 **/
6 keySelector: string
7 /** 您的私鑰。以 -----BEGIN PRIVATE KEY----- 開頭，並以 -----END PRIVATE KEY----- 結尾。 **/
8 privateKey: string
9}
10
用於驗證
網域設定用來決定哪些網站可以為您的帳戶承載 FastComments 小工具。這是一種基本的驗證方式，也就是說，新增或移除任何網域設定可能會影響您生產環境中 FastComments 安裝的可用性。
除非您打算停用該網域，否則不要移除或更新目前正在使用之網域的 Domain Config 中的 domain 屬性。
這與從 /auth/my-account/configure-domains 中移除網域的行為相同。
另請注意，從 My Domains UI 移除網域也會刪除此介面中為該網域新增的任何對應設定。
用於電子郵件自訂
電子郵件頁尾的退訂連結，以及許多郵件用戶端提供的一鍵退訂功能，可以透過此 API 分別定義 footerUnsubscribeURL 與 emailHeaders 來設定。
用於 DKIM
在定義好 DKIM 的 DNS 紀錄後，只需使用上述結構將您的 DKIM 設定更新到 DomainConfig 即可。
GET /api/v1/domain-configs
Resource: Comment as GET /api/v1/domain-configs Credit Cost: 1
此 API 提供擷取租戶的所有 DomainConfig 物件的功能。
DomainConfig GET cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/domain-configs?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
DomainConfig GET 請求結構
Copy
1
2interface GetDomainConfigsRequestQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
DomainConfig GET 回應結構
Copy
1
2interface GetDomainConfigsResponse {
3 status: 'success' | 'failed'
4 /** 僅於失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
6 /** 僅於失敗時包含。 **/
7 reason?: string
8 /** 這些設定！ **/
9 configurations: DomainConfig[] | null
10}
11
GET /api/v1/domain-configs/:domain
Resource: DomainConfig as GET /api/v1/domain-configs/:domain Credit Cost: 1
可根據對應的 domain 取得個別的 DomainConfigs。
以 domain 取得 Domain Config 的 cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/domain-configs/example.com?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
以 domain 取得 Domain Config 的請求結構
Copy
1
2interface DomainConfigsByDomainRequestQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
以 domain 取得 Domain Config 的回應結構
Copy
1
2interface DomainConfigResponse {
3 status: 'success' | 'failed'
4 /** 於失敗時包含。 **/
5 code?: 'internal' | 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'missing-domain' | 'update-would-create-duplicate' | 'domain-does-not-exist'
6 /** 於失敗時包含。 **/
7 reason?: string
8 configuration?: DomainConfig | null
9}
10
POST /api/v1/domain-configs
Resource: DomainConfig as POST /api/v1/domain-configs Credit Cost: 1
此 API 端點提供建立網域設定的功能。
為網域新增設定會授權該網域使用 FastComments 帳戶。
此 API 的常見使用情境包括初始設定、需要新增多個網域時，或為發送電子郵件做自訂設定。
DomainConfig POST cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/domain-configs?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "domain": "example.com",
7 "emailFromName": "some from name",
8 "emailFromEmail": "some@test.com",
9 "logoSrc": "https://example.com/my-logo-big.png",
10 "logoSrc100px": "https://example.com/my-logo-100px.png",
11 "footerUnsubscribeURL": "http://example.com/unsubscribe-ui",
12 "emailHeaders": {
13 "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
14 "List-Unsubscribe": "<https://example.com/opt-out/[userId]>"
15 }
16}'
17
DomainConfig POST 請求結構
Copy
1
2interface DomainConfigPostQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
DomainConfig POST 回應結構
Copy
1
2
3interface DomainConfigPostResponse {
4 status: 'success' | 'failed'
5 /** 失敗時會包含。 **/
6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'missing-domain' | 'configuration-exists-for-domain' | 'domain-too-long' | 'domain-invalid';
7 /** 失敗時會包含。 **/
8 reason?: string
9 /** 已建立的設定。 **/
10 configuration?: DomainConfig
11}
12
PATCH /api/v1/domain-configs/:domain
Resource: DomainConfig as PATCH /api/v1/domain-configs/:domain Credit Cost: 1
此 API 端點允許透過僅指定網域與要更新的屬性來更新網域設定。
DomainConfig PATCH cURL 範例
Copy
1
2curl --request PATCH \
3 --url 'https://fastcomments.com/api/v1/domain-configs/example.com?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "emailFromName": "Some New From Name",
7}'
8
DomainConfig PATCH 請求結構
Copy
1
2interface DomainConfigPatchQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
DomainConfig PATCH 回應結構
Copy
1
2
3interface DomainConfigPatchResponse {
4 status: 'success' | 'failed'
5 /** 在失敗時包含。 **/
6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'missing-domain' | 'domain-does-not-exist' | 'update-would-create-duplicate' | 'domain-too-long' | 'domain-invalid';
7 /** 在失敗時包含。 **/
8 reason?: string
9 /** 已更新的設定。 **/
10 configuration?: DomainConfig
11}
12
PUT /api/v1/domain-configs/:domain
Resource: DomainConfig as PUT /api/v1/domain-configs/:domain Credit Cost: 1
此 API 端點提供替換網域設定的功能。
DomainConfig PUT cURL 範例
Copy
1
2curl --request PUT \
3 --url 'https://fastcomments.com/api/v1/domain-configs/example.com?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "domain": "new-domain-example.com",
7 "emailFromName": "some from name",
8 "emailFromEmail": "some@test.com",
9 "logoSrc": "https://example.com/my-logo-big.png",
10 "logoSrc100px": "https://example.com/my-logo-100px.png",
11 "footerUnsubscribeURL": "http://example.com/unsubscribe-ui",
12 "emailHeaders": {
13 "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
14 "List-Unsubscribe": "<https://example.com/opt-out/[userId]>"
15 }
16}'
17
DomainConfig PUT 請求結構
Copy
1
2interface DomainConfigPutQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
DomainConfig PUT 回應結構
Copy
1
2
3interface DomainConfigPutResponse {
4 status: 'success' | 'failed'
5 /** 僅在失敗時包含。 **/
6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'missing-domain' | 'domain-does-not-exist' | 'update-would-create-duplicate' | 'domain-too-long' | 'domain-invalid';
7 /** 僅在失敗時包含。 **/
8 reason?: string
9 /** 更新後的設定。 **/
10 configuration?: DomainConfig
11}
12
DELETE /api/v1/domain-configs/:domain
Resource: DomainConfig as DELETE /api/v1/domain-configs/:domain Credit Cost: 1
此路由提供透過 id 移除單一 DomainConfig 的功能。
- 注意：移除
DomainConfig將會取消該網域使用 FastComments 的授權。 - 注意：透過 UI 重新新增網域會重新建立該物件（只會填入
domain）。
DomainConfig 刪除 cURL 範例
Copy
1
2curl --request DELETE \
3 --url 'https://fastcomments.com/api/v1/domain-configs/example.com?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
DomainConfig 刪除請求結構
Copy
1
2interface DomainConfigRequestQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
DomainConfig 刪除回應結構
Copy
1
2interface DomainConfigDeleteResponse {
3 status: 'success' | 'failed'
4 /** 僅於失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-domain' | 'domain-config-does-not-exist'
6 /** 僅於失敗時包含。 **/
7 reason?: string
8}
9
問題設定結構
FastComments 提供了一種建立問題並彙總其結果的方法。問題的一個範例（以下稱為 QuestionConfig）
可以是星級評分、滑桿，或 NPS 問題（由 type 決定）。
問題資料可以單獨彙總、合併彙總、按時間、整體、按頁面等方式彙總。
此框架具備建置客戶端小工具（由您的伺服器置於此 API 之前）、管理儀表板與報表工具所需的所有功能。
首先，我們需要定義一個 QuestionConfig。結構如下：
QuestionConfig 結構
Copy
1
2type QuestionConfigType = 'nps' | 'slider' | 'star' | 'thumbs';
3
4interface QuestionConfig {
5 id: string
6 tenantId: string
7 name: string
8 question: string
9 helpText?: string
10 createdAt: string
11 createdBy: string
12 /** 只讀 - 每新增一個回應即遞增。 **/
13 usedCount: number
14 /** 表示設定最後使用（有結果留下）的日期字串。 **/
15 lastUsed?: string
16 type: QuestionConfigType
17 numStars?: number
18 min?: number
19 max?: number
20 defaultValue?: number
21 labelNegative?: string
22 labelPositive?: string
23 subQuestionIds?: string[]
24 alwaysShowSubQuestions?: boolean
25 reportingOrder: number
26}
27
GET /api/v1/question-configs
Resource: QuestionConfig as GET /api/v1/question-configs Credit Cost: 1
此路由會一次回傳最多 100 個 QuestionConfig 物件，並採用分頁。每 100 個物件的成本為 1。它們會
依照問題文字以升冪排序（question 欄位）。
QuestionConfig 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/question-configs?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
QuestionConfig 請求結構
Copy
1
2interface QuestionConfigRequestByIdQueryParams {
3 tenantId: string
4 API_KEY: string
5 /** 用於分頁。從 0 開始。 **/
6 skip?: number
7}
8
QuestionConfig 回應結構
Copy
1
2interface QuestionConfigByIdResponse {
3 status: 'success' | 'failed'
4 /** 失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
6 /** 失敗時包含。 **/
7 reason?: string
8 questionConfigs: QuestionConfig[]
9}
10
GET /api/v1/question-configs/:id
Resource: QuestionConfig as GET /api/v1/question-configs/:id Credit Cost: 1
此路由會依其 id 回傳單一個 QuestionConfig。
QuestionConfig 依 ID 的 cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/question-configs/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
QuestionConfig 請求結構
Copy
1
2interface QuestionConfigRequestByIdQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
QuestionConfig 回應結構
Copy
1
2interface QuestionConfigByIdResponse {
3 status: 'success' | 'failed'
4 /** 失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
6 /** 失敗時包含。 **/
7 reason?: string
8 questionConfig?: QuestionConfig
9}
10
POST /api/v1/question-configs
Resource: QuestionConfig as POST /api/v1/question-configs Credit Cost: 1
此 API 端點提供建立 QuestionConfig 的功能。
QuestionConfig POST cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/question-configs?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "name": "Some name that shows on reports.",
7 "question": "how much do you like this api?",
8 "type": 'slider',
9 "reportingOrder": 0,
10 "min": 0,
11 "max": 10
12}'
13
QuestionConfig POST 請求結構
Copy
1
2interface QuestionConfigPostQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
QuestionConfig POST 回應結構
Copy
1
2
3interface QuestionConfigPostResponse {
4 status: 'success' | 'failed'
5 /** 失敗時包含。 **/
6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input';
7 /** 失敗時包含。 **/
8 reason?: string
9 /** 已建立的物件。 **/
10 questionConfig?: QuestionConfig
11}
12
PATCH /api/v1/question-configs/:id
Resource: QuestionConfig as PATCH /api/v1/question-configs/:id Credit Cost: 1
此路由提供更新單一個 QuestionConfig 的功能。
下列結構表示可更改的所有值：
QuestionConfig 結構
Copy
1
2interface QuestionConfigPatchBody {
3 name?: string
4 question?: string
5 helpText?: string
6 /** 注意！若 min/max 不同，變更 type 可能會影響報表。 **/
7 type?: QuestionConfigType
8 numStars?: number
9 min?: number
10 max?: number
11 defaultValue?: number
12 labelNegative?: string
13 labelPositive?: string
14 subQuestionIds?: string[]
15 alwaysShowSubQuestions?: boolean
16 reportingOrder?: number
17}
18
QuestionConfig 更新 cURL 範例
Copy
1
2curl --request PATCH \
3 --url 'https://fastcomments.com/api/v1/question-configs/my-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "question": "some new question text"
7}'
8
QuestionConfig 更新請求結構
Copy
1
2interface QuestionConfigPatchQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
QuestionConfig 更新回應結構
Copy
1
2interface QuestionConfigPatchResponse {
3 status: 'success' | 'failed'
4 /** 於失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'unauthorized' | 'missing-api-key' | 'missing-id' | 'not-found' | 'empty-request' | 'invalid-input'
6 /** 於失敗時包含。 **/
7 reason?: string
8}
9
DELETE /api/v1/question-configs/:id
Resource: QuestionConfig as DELETE /api/v1/question-configs/:id Credit Cost: 100
此路由提供透過 id 刪除 QuestionConfig。
這會刪除所有對應的問題結果（但不會刪除評論）。 這是高信用成本的一部分。
QuestionConfig 刪除 cURL 範例
Copy
1
2curl --request DELETE \
3 --url 'https://fastcomments.com/api/v1/question-configs/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
QuestionConfig 刪除請求結構
Copy
1
2interface QuestionConfigDeleteQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
QuestionConfig 刪除回應結構
Copy
1
2interface QuestionConfigResponse {
3 status: 'success' | 'failed'
4 /** 失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
6 /** 失敗時包含。 **/
7 reason?: string
8}
9
問題結果結構
為了儲存問題的結果，您需要建立一個 QuestionResult。接著您可以彙總問題結果，並且將它們
與評論關聯以便進行報告。
QuestionResult 結構
Copy
1
2interface QuestionResultMeta {
3 name: string
4 values: string[]
5}
6
7interface QuestionResult {
8 id: string
9 tenantId: string
10 urlId: string
11 anonUserId?: string
12 userId?: string
13 createdAt?: string
14 value: number
15 commentId?: string
16 questionId: string
17 meta?: QuestionResultMeta[]
18}
19
GET /api/v1/question-results
Resource: QuestionResults as GET /api/v1/question-results Credit Cost: 1
此路由一次最多傳回 1000 個 QuestionResults 物件，分頁回傳。費用為每 100 個物件 1。
它們依 createdAt 升序排序。您可以依各種參數進行篩選。
QuestionResults 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/question-results?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
QuestionResults 請求結構
Copy
1
2interface QuestionResultsRequestQueryParams {
3 tenantId: string
4 API_KEY: string
5 /** 用於分頁。從 0 開始。 **/
6 skip?: number
7 /** 用於分頁。 **/
8 limit?: number
9 /** 取得特定頁面的結果。 **/
10 urlId?: string
11 /** 取得特定使用者的結果。 **/
12 userId?: string
13 startDate?: string | number
14 questionId?: string | string[]
15}
16
QuestionResults 回應結構
Copy
1
2interface QuestionResultsResponse {
3 status: 'success' | 'failed'
4 /** 失敗時會包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
6 /** 失敗時會包含。 **/
7 reason?: string
8 questionResults: QuestionResults[]
9}
10
GET /api/v1/question-results/:id
Resource: QuestionResult as GET /api/v1/question-results/:id Credit Cost: 1
此路由會根據其 id 回傳單一 QuestionResult。
QuestionResult 根據 ID 的 cURL 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/question-results/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
QuestionResult 請求結構
Copy
1
2interface QuestionResultRequestByIdQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
QuestionResult 回應結構
Copy
1
2interface QuestionResultByIdResponse {
3 status: 'success' | 'failed'
4 /** 僅在失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
6 /** 僅在失敗時包含。 **/
7 reason?: string
8 questionResult?: QuestionResult
9}
10
POST /api/v1/question-results
Resource: QuestionResult as POST /api/v1/question-results Credit Cost: 1
此 API 端點提供建立 QuestionResult 的功能。
QuestionResult POST cURL 範例
Copy
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/question-results?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "urlId": "some-page-id",
7 "anonUserId": 'anon-0',
8 "userId": 'user-0',
9 "value": 10,
10 "questionId": "some-question-id",
11 "meta": [
12 {
13 name: "example",
14 values: ["value-1", "value-2"]
15 }
16 ]
17}'
18
QuestionResult POST 請求結構
Copy
1
2interface QuestionResultPostQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
QuestionResult POST 回應結構
Copy
1
2
3interface QuestionResultPostResponse {
4 status: 'success' | 'failed'
5 /** 僅於失敗時包含。 **/
6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input';
7 /** 僅於失敗時包含。 **/
8 reason?: string
9 /** 已建立的物件。 **/
10 questionResult?: QuestionResult
11}
12
PATCH /api/v1/question-results/:id
Resource: QuestionResult as PATCH /api/v1/question-results/:id Credit Cost: 1
此路由提供更新單一 QuestionResult 的功能。
下列結構表示所有可變更的值：
QuestionResult 結構
Copy
1
2interface QuestionResultPatchBody {
3 urlId?: string
4 anonUserId?: string
5 userId?: string
6 value?: string
7 commentId?: string
8 questionId?: string
9 meta?: QuestionResultMeta[]
10}
11
QuestionResult 更新 cURL 範例
Copy
1
2curl --request PATCH \
3 --url 'https://fastcomments.com/api/v1/question-results/my-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "value": 5
7}'
8
QuestionResult 更新請求結構
Copy
1
2interface QuestionResultPatchQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
QuestionResult 更新回應結構
Copy
1
2interface QuestionResultPatchResponse {
3 status: 'success' | 'failed'
4 /** 於失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'unauthorized' | 'missing-api-key' | 'missing-id' | 'not-found' | 'empty-request' | 'invalid-input'
6 /** 於失敗時包含。 **/
7 reason?: string
8}
9
DELETE /api/v1/question-results/:id
Resource: QuestionResult as DELETE /api/v1/question-results/:id Credit Cost: 1
此路由可用於依 id 刪除 QuestionResult。
QuestionResult 刪除 cURL 範例
Copy
1
2curl --request DELETE \
3 --url 'https://fastcomments.com/api/v1/question-results/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
QuestionResult 刪除請求結構
Copy
1
2interface QuestionResultDeleteQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
QuestionResult 刪除回應結構
Copy
1
2interface QuestionResultResponse {
3 status: 'success' | 'failed'
4 /** 失敗時包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
6 /** 失敗時包含。 **/
7 reason?: string
8}
9
GET /api/v1/question-results-aggregate
Resource: QuestionResultsAggregate as GET /api/v1/question-results-aggregate Credit Cost: 2
這裡是結果彙總的地方。
彙總回應結構如下：
QuestionResultsAggregationResult 結構
Copy
1
2interface QuestionResultDataPoint {
3 /** 當前資料點（日期區段或頁面）中，將值映射到該值出現次數的映射。 **/
4 v: Map<ValueAsString, number>
5 total: number
6}
7
8interface QuestionResultsAggregationResult {
9 /** Note - is null when timeBucket not specified. **/
10 dataByDateBucket?: Map<DateString, QuestionResultDataPoint>
11 dataByUrlId?: Map<URLIdString, QuestionResultDataPoint>
12 countsByValue?: Map<ValueAsString, number>
13 /** 彙總的結果總數。 **/
14 total: number
15 /** 計算出的加權平均值。為浮點數，通常為兩位小數或更少。 **/
16 average: number
17 /** 表示此資料計算時間的日期字串，因為資料可能來自快取。 **/
18 createdAt: string
19}
20
Here are the query parameters available for aggregation:
QuestionResultsAggregation 請求結構
Copy
1
2interface QuestionResultsAggregateRequestQueryParams {
3 tenantId: string
4 API_KEY: string
5 /** You can aggregate results for one or more questions. **/
6 questionId: string | string[]
7 startDate?: string | number
8 timeBucket?: 'day' | 'month' | 'year'
9 /** Aggregate for a specific page. **/
10 urlId?: string
11 /** Aggregate for a specific user. **/
12 userId?: string
13 /** Force recalculate now and update the cache. **/
14 forceRecalculate?: boolean
15}
16
Here's an example request:
QuestionResultsAggregation 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/question-results-aggregation?tenantId=demo&API_KEY=DEMO_API_SECRET&questionId=some-question-id'
4
Example response:
QuestionResultsAggregation 回應範例
Copy
1
2 {
3 "average": 8.33,
4 "countsByValue": {
5 "5": 1,
6 "10": 2
7 },
8 "createdAt": "2023-08-30T00:00:00.000Z",
9 "dataByUrlId": {
10 "some-page": {
11 "total": 3,
12 "v": {
13 "5": 1,
14 "10": 2
15 }
16 }
17 },
18 "total": 3
19 }
20
QuestionResultsAggregation 回應結構
Copy
1
2interface QuestionResultsAggregationResponse {
3 status: 'success' | 'failed'
4 /** Included on failure. **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
6 /** Included on failure. **/
7 reason?: string
8 data: QuestionResultsAggregationResult
9}
10
效能注意事項
- 對於快取未命中，彙總通常每百萬筆結果約需五秒。
- 否則，請求為常數時間。
快取與費用說明
- 當
forceRecalculate是指定時，費用恆為10，而不是一般的2。 - 如果快取過期且資料被重新計算，若未指定
forceRecalculate，費用仍為固定的2。快取的過期時間取決於被彙總資料集的大小（可介於 30 秒到 5 分鐘之間）。 - 此機制是為了鼓勵使用快取。
GET /api/v1/question-results-aggregate/combine/comments
Resource: QuestionResultsCombinedWithComments as GET /api/v1/question-results-aggregate/combine/comments Credit Cost: 2
這是將結果與留言結合的地方。舉例來說，對於建立某產品的「最近正面與負面留言」圖表非常有用。
你可以透過一個值範圍（包含端點）、一個或多個問題，以及起始日期（包含）來搜尋。
回應結構如下：
QuestionResultsCombinedWithCommentsResponse 結構
Copy
1
2interface SimpleComment {
3 id: string
4 commenterName: string
5 userId?: string
6 date: string
7 commentHTML: string
8}
9
10interface SimpleQuestionResult {
11 id: string
12 value: number
13}
14
15interface CommentAndResult {
16 comment: SimpleComment
17 result: SimpleQuestionResult
18}
19
20interface QuestionResultsCombinedWithCommentsResponse {
21 /** 表示何時計算此資料的日期字串，因為資料可能來自快取。 **/
22 createdAt: string
23 results: CommentAndResult[]
24}
25
以下是可用於彙總的查詢參數：
QuestionResultsCombineComments 請求結構
Copy
1
2interface QuestionResultsAggregateRequestQueryParams {
3 tenantId: string
4 API_KEY: string
5 /** 你可以為一個或多個問題彙總結果。 **/
6 questionId: string | string[]
7 startDate?: string | number
8 urlId?: string
9 minValue: number
10 maxValue: number
11 limit?: number
12 forceRecalculate?: boolean
13}
14
這是一個範例請求：
QuestionResultsCombineComments 範例
Copy
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/question-results-aggregation/combine/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&questionId=some-question-id&minValue=5&maxValue=10'
4
範例回應：
QuestionResultsCombineComments 回應範例
Copy
1
2{
3 "createdAt": "2023-08-30T00:00:00.000Z",
4 "results": [
5 {
6 "comment": {
7 "id": "some-id",
8 "commentHTML": "test-2",
9 "commenterName": "Test",
10 "date": "2023-08-30T00:00:00.000Z",
11 "userId": "some-user-id"
12 },
13 "result": {
14 "id": "some-id",
15 "value": 10
16 }
17 },
18 {
19 "comment": {
20 "id": "some-id",
21 "commentHTML": "test-0",
22 "commenterName": "Some Name",
23 "date": "2023-08-30T00:00:00.000Z",
24 "userId": "some-user-id"
25 },
26 "result": {
27 "id": "some-id",
28 "value": 5
29 }
30 }
31 ]
32}
33
QuestionResultsCombineComments 回應結構
Copy
1
2interface QuestionResultsCombineCommentsResponse {
3 status: 'success' | 'failed'
4 /** 失敗時會包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
6 /** 失敗時會包含。 **/
7 reason?: string
8 data: QuestionResultsCombinedWithCommentsResponse
9}
10
快取與成本說明
- 當指定
forceRecalculate時，成本固定為10，而非通常的2。 - 如果快取過期且資料被重新計算，若未指定
forceRecalculate，成本仍維持常數2。 - 這是為了鼓勵使用快取。
使用者徽章結構
UserBadge 是一個物件，代表分配給 FastComments 系統中使用者的徽章。
徽章可以根據使用者的活動自動分配（例如留言數、回覆時間、資深使用者狀態），或由網站管理員手動分配。
以下為 UserBadge 物件的結構：
UserBadge 結構
Copy
1
2export interface UserBadge {
3 /** 此使用者徽章分配的唯一識別碼 */
4 id: string
5 /** 此徽章所指派之使用者的 ID */
6 userId: string
7 /** 來自租戶徽章目錄的徽章定義 ID */
8 badgeId: string
9 /** 建立/指派此徽章的租戶 ID */
10 fromTenantId: string
11 /** 此徽章建立時間（以 epoch 起算的毫秒） */
12 createdAt?: number
13 /** 使用者收到此徽章的時間（以 epoch 起算的毫秒） */
14 receivedAt?: number
15 /**
16 * 徽章類型：
17 * 0=CommentCount, 1=CommentUpVotes, 2=CommentReplies, 3=CommentsPinned,
18 * 4=Veteran, 5=NightOwl, 6=FastReplyTime, 7=ModeratorCommentsDeleted,
19 * 8=ModeratorCommentsApproved, 9=ModeratorCommentsUnapproved, 10=ModeratorCommentsReviewed,
20 * 11=ModeratorCommentsMarkedSpam, 12=ModeratorCommentsMarkedNotSpam, 13=RepliedToSpecificPage,
21 * 14=Manual
22 */
23 type: number
24 /** 對於以門檻為條件的徽章，門檻值 */
25 threshold?: number
26 /** 徽章的名稱/標籤 */
27 name?: string
28 /** 徽章的詳細描述 */
29 description?: string
30 /** 徽章上顯示的文字 */
31 displayLabel?: string
32 /** 徽章上顯示的圖片 URL */
33 displaySrc?: string
34 /** 徽章的背景顏色（十六進位碼） */
35 backgroundColor?: string
36 /** 徽章的邊框顏色（十六進位碼） */
37 borderColor?: string
38 /** 徽章的文字顏色（十六進位碼） */
39 textColor?: string
40 /** 用於樣式的額外 CSS 類別 */
41 cssClass?: string
42 /** 對於資深徽章，時間門檻（毫秒） */
43 veteranUserThresholdMillis?: number
44 /** 此徽章是否顯示在使用者的留言上 */
45 displayedOnComments: boolean
46 /** 徽章的顯示順序 */
47 order?: number
48}
49
GET /api/v1/user-badges
此端點允許您根據各種條件取得使用者徽章。
Example Request:
GET 請求範例
Copy Run
Run 1
2curl -X GET "https://fastcomments.com/api/v1/user-badges?tenantId=demo&API_KEY=DEMO_API_SECRET"
3
You can add various query parameters to filter the results:
userId- 取得特定使用者的徽章badgeId- 取得特定徽章的實例type- 依徽章類型篩選 (0=CommentCount, 1=CommentUpVotes, 2=CommentReplies, etc. See UserBadge structure for full list)displayedOnComments- 根據徽章是否顯示於評論上篩選 (true/false)limit- 要返回的徽章最多數量 (預設 30, max 200)skip- 要跳過的徽章數量 (for pagination)
Example Response:
回應
Copy
1
2{
3 "status": "success",
4 "userBadges": [
5 {
6 "id": "badge123",
7 "userId": "user456",
8 "badgeId": "badgeDef789",
9 "fromTenantId": "tenant001",
10 "createdAt": 1650532511000,
11 "receivedAt": 1650532511000,
12 "type": 14,
13 "name": "Special Contributor",
14 "description": "Awarded to special contributors to our community",
15 "displayLabel": "Special",
16 "backgroundColor": "#4a5568",
17 "textColor": "#ffffff",
18 "displayedOnComments": true,
19 "order": 1
20 },
21 {
22 "id": "badge124",
23 "userId": "user456",
24 "badgeId": "badgeDef790",
25 "fromTenantId": "tenant001",
26 "createdAt": 1650532598000,
27 "receivedAt": 1650532598000,
28 "type": 0,
29 "threshold": 100,
30 "name": "Centurion",
31 "description": "Made 100 comments",
32 "displayLabel": "100",
33 "backgroundColor": "#2b6cb0",
34 "textColor": "#ffffff",
35 "displayedOnComments": true,
36 "order": 2
37 }
38 ]
39}
40
Possible Error Responses:
錯誤：缺少租戶 ID
Copy
1
2{
3 "status": "failed",
4 "code": "missing-tenant-id",
5 "reason": "Tenant ID (query param: tenantId) is missing."
6}
7
錯誤：無效的 limit
Copy
1
2{
3 "status": "failed",
4 "code": "invalid-limit",
5 "reason": "The limit (query param: limit) is too large (> 200)."
6}
7
GET /api/v1/user-badges/:id
此端點允許您透過其唯一 ID 取得特定使用者徽章。
範例請求：
GET 請求範例
Copy Run
Run 1
2curl -X GET "https://fastcomments.com/api/v1/user-badges/badge123?tenantId=demo&API_KEY=DEMO_API_SECRET"
3
範例回應：
回應
Copy
1
2{
3 "status": "success",
4 "userBadge": {
5 "id": "badge123",
6 "userId": "user456",
7 "badgeId": "badgeDef789",
8 "fromTenantId": "tenant001",
9 "createdAt": 1650532511000,
10 "receivedAt": 1650532511000,
11 "type": 14,
12 "name": "Special Contributor",
13 "description": "Awarded to special contributors to our community",
14 "displayLabel": "Special",
15 "backgroundColor": "#4a5568",
16 "textColor": "#ffffff",
17 "displayedOnComments": true,
18 "order": 1
19 }
20}
21
可能的錯誤回應：
錯誤：缺少租戶 ID
Copy
1
2{
3 "status": "failed",
4 "code": "missing-tenant-id",
5 "reason": "Tenant ID (query param: tenantId) is missing."
6}
7
錯誤：未找到
Copy
1
2{
3 "status": "failed",
4 "code": "not-found",
5 "reason": "The user badge badge123 was not found."
6}
7
POST /api/v1/user-badges
此端點允許您建立新的使用者徽章指派。
Example Request:
POST 請求範例
Copy Run
Run 1
2curl -X POST "https://fastcomments.com/api/v1/user-badges?tenantId=demo&API_KEY=DEMO_API_SECRET" \
3-H "Content-Type: application/json" \
4-d '{
5 "userId": "user456",
6 "badgeId": "badgeDef789",
7 "displayedOnComments": true
8}'
9
The request body must contain the following parameters:
userId(required) - 要指派徽章之使用者的 IDbadgeId(required) - 要指派之徽章的 IDdisplayedOnComments(optional) - 是否應在使用者的留言上顯示該徽章（預設為 true）
Important Notes:
- The badge must exist and be enabled in your tenant's badge catalog
- You can only assign badges to users who belong to your tenant or have commented on your site
Example Response:
回應
Copy
1
2{
3 "status": "success",
4 "userBadge": {
5 "id": "badge123",
6 "userId": "user456",
7 "badgeId": "badgeDef789",
8 "fromTenantId": "tenant001",
9 "createdAt": 1650532511000,
10 "receivedAt": 1650532511000,
11 "type": 14,
12 "name": "Special Contributor",
13 "description": "Awarded to special contributors to our community",
14 "displayLabel": "Special",
15 "backgroundColor": "#4a5568",
16 "textColor": "#ffffff",
17 "displayedOnComments": true,
18 "order": 1
19 }
20}
21
Possible Error Responses:
錯誤：缺少租戶 ID
Copy
1
2{
3 "status": "failed",
4 "code": "missing-tenant-id",
5 "reason": "Tenant ID (query param: tenantId) is missing."
6}
7
錯誤：缺少使用者 ID
Copy
1
2{
3 "status": "failed",
4 "code": "missing-user-id",
5 "reason": "User ID (body param: userId) is required."
6}
7
錯誤：缺少徽章 ID
Copy
1
2{
3 "status": "failed",
4 "code": "missing-badge-id",
5 "reason": "Badge ID (body param: badgeId) is required."
6}
7
錯誤：找不到徽章
Copy
1
2{
3 "status": "failed",
4 "code": "badge-not-found",
5 "reason": "The badge badgeDef789 was not found or is not enabled."
6}
7
錯誤：未授權的使用者
Copy
1
2{
3 "status": "failed",
4 "code": "unauthorized-user",
5 "reason": "You can only add badges to users who belong to your tenant or have commented on your site."
6}
7
PUT /api/v1/user-badges/:id
此端點允許您更新使用者徽章指派。
目前，唯一可更新的屬性是 displayedOnComments，它用來控制該徽章是否在使用者的評論上顯示。
Example Request:
PUT 請求範例
Copy Run
Run 1
2curl -X PUT "https://fastcomments.com/api/v1/user-badges/badge123?tenantId=demo&API_KEY=DEMO_API_SECRET" \
3-H "Content-Type: application/json" \
4-d '{
5 "displayedOnComments": false
6}'
7
Example Response:
回應
Copy
1
2{
3 "status": "success"
4}
5
Possible Error Responses:
錯誤：缺少租戶 ID
Copy
1
2{
3 "status": "failed",
4 "code": "missing-tenant-id",
5 "reason": "Tenant ID (query param: tenantId) is missing."
6}
7
錯誤：缺少 ID
Copy
1
2{
3 "status": "failed",
4 "code": "missing-id",
5 "reason": "The User Badge ID (url param: id) is missing."
6}
7
錯誤：未找到
Copy
1
2{
3 "status": "failed",
4 "code": "not-found",
5 "reason": "The user badge badge123 was not found."
6}
7
DELETE /api/v1/user-badges/:id
此端點允許您刪除使用者徽章指派。
範例請求：
DELETE 請求範例
Copy Run
Run 1
2curl -X DELETE "https://fastcomments.com/api/v1/user-badges/badge123?tenantId=demo&API_KEY=DEMO_API_SECRET"
3
範例回應：
回應
Copy
1
2{
3 "status": "success"
4}
5
可能的錯誤回應：
錯誤：缺少租戶 ID
Copy
1
2{
3 "status": "failed",
4 "code": "missing-tenant-id",
5 "reason": "Tenant ID (query param: tenantId) is missing."
6}
7
錯誤：缺少 ID
Copy
1
2{
3 "status": "failed",
4 "code": "missing-id",
5 "reason": "The User Badge ID (url param: id) is missing."
6}
7
錯誤：未找到
Copy
1
2{
3 "status": "failed",
4 "code": "not-found",
5 "reason": "The user badge badge123 was not found."
6}
7
使用者徽章進度結構
UserBadgeProgress 是一個物件，表示使用者在 FastComments 系統中獲取各種徽章的進度。
此追蹤有助於根據使用者在您的社群中的活動與參與來決定何時應該自動授予徽章。
UserBadgeProgress 物件的結構如下：
UserBadgeProgress 結構
Copy
1
2export interface UserBadgeProgress {
3 /** 此進度記錄的唯一識別碼 */
4 id: string
5 /** 此進度記錄所屬的租戶 ID */
6 tenantId: string
7 /** 此進度記錄所追蹤的使用者 ID */
8 userId: string
9 /** 使用者在系統中的第一則評論的 ID */
10 firstCommentId?: string
11 /** 使用者第一則評論的日期（自 epoch 起的毫秒數） */
12 firstCommentDate?: number
13 /** 根據使用者活動自動計算的信任係數 */
14 autoTrustFactor?: number
15 /** 由管理員手動設定的信任係數 */
16 manualTrustFactor?: number
17 /** 包含各種指標的詳細進度物件，鍵與 BadgeType enum 相符 */
18 progress: {
19 /** 0: CommentCount - 使用者發表評論的數量 */
20 '0'?: number
21 /** 1: CommentUpVotes - 使用者收到的讚數 */
22 '1'?: number
23 /** 2: CommentReplies - 使用者發表的回覆數 */
24 '2'?: number
25 /** 3: CommentsPinned - 使用者被固定的評論數 */
26 '3'?: number
27 /** 4: Veteran - 使用者帳戶年齡 */
28 '4'?: number
29 /** 5: NightOwl - 使用者在夜間時段發文的次數 */
30 '5'?: number
31 /** 6: FastReplyTime - 平均回覆時間（毫秒） */
32 '6'?: number
33 /** 7: ModeratorCommentsDeleted - 對於管理員徽章，刪除的評論數 */
34 '7'?: number
35 /** 8: ModeratorCommentsApproved - 對於管理員徽章，核准的評論數 */
36 '8'?: number
37 /** 9: ModeratorCommentsUnapproved - 對於管理員徽章，未核准的評論數 */
38 '9'?: number
39 /** 10: ModeratorCommentsReviewed - 對於管理員徽章，已審核的評論數 */
40 '10'?: number
41 /** 11: ModeratorCommentsMarkedSpam - 對於管理員徽章，被標記為垃圾評論的數量 */
42 '11'?: number
43 /** 12: ModeratorCommentsMarkedNotSpam - 對於管理員徽章，被標記為非垃圾評論的數量 */
44 '12'?: number
45 /** 13: RepliedToSpecificPage - 每個頁面的回覆數量 */
46 '13'?: Record<string, number>
47 }
48}
49
GET /api/v1/user-badge-progress
此端點允許您根據各種條件取得使用者徽章進度紀錄。
範例請求：
GET 請求範例
Copy Run
Run 1
2curl -X GET "https://fastcomments.com/api/v1/user-badge-progress?tenantId=demo&API_KEY=DEMO_API_SECRET"
3
您可以加入各種查詢參數來篩選結果：
userId- 取得特定使用者的進度紀錄limit- 要返回的最大紀錄數（預設 30，最大 200）skip- 要跳過的紀錄數（用於分頁）
範例回應：
回應
Copy
1
2{
3 "status": "success",
4 "userBadgeProgresses": [
5 {
6 "id": "progress123",
7 "tenantId": "tenant001",
8 "userId": "user456",
9 "firstCommentId": "comment789",
10 "firstCommentDate": 1650532511000,
11 "autoTrustFactor": 0.75,
12 "progress": {
13 "0": 42,
14 "1": 120,
15 "2": 15,
16 "3": 3,
17 "5": 5,
18 "6": 1800000,
19 "8": 0,
20 "7": 0
21 }
22 },
23 {
24 "id": "progress124",
25 "tenantId": "tenant001",
26 "userId": "user789",
27 "firstCommentId": "comment790",
28 "firstCommentDate": 1650532598000,
29 "autoTrustFactor": 0.5,
30 "progress": {
31 "0": 12,
32 "1": 15,
33 "2": 4
34 }
35 }
36 ]
37}
38
可能的錯誤回應：
錯誤：缺少租戶 ID
Copy
1
2{
3 "status": "failed",
4 "code": "missing-tenant-id",
5 "reason": "Tenant ID (query param: tenantId) is missing."
6}
7
錯誤：無效的限制
Copy
1
2{
3 "status": "failed",
4 "code": "invalid-limit",
5 "reason": "The limit (query param: limit) is too large (> 200)."
6}
7
GET /api/v1/user-badge-progress/:id
此端點允許您透過其唯一 ID 擷取特定使用者徽章進度紀錄。
範例請求:
GET 請求範例
Copy Run
Run 1
2curl -X GET "https://fastcomments.com/api/v1/user-badge-progress/progress123?tenantId=demo&API_KEY=DEMO_API_SECRET"
3
範例回應:
回應
Copy
1
2{
3 "status": "success",
4 "userBadgeProgress": {
5 "id": "progress123",
6 "tenantId": "tenant001",
7 "userId": "user456",
8 "firstCommentId": "comment789",
9 "firstCommentDate": 1650532511000,
10 "autoTrustFactor": 0.75,
11 "progress": {
12 "0": 42,
13 "1": 120,
14 "2": 15,
15 "3": 3,
16 "5": 5,
17 "6": 1800000,
18 "8": 0,
19 "7": 0
20 }
21 }
22}
23
可能的錯誤回應:
錯誤：缺少租戶 ID
Copy
1
2{
3 "status": "failed",
4 "code": "missing-tenant-id",
5 "reason": "Tenant ID (query param: tenantId) is missing."
6}
7
錯誤：未找到
Copy
1
2{
3 "status": "failed",
4 "code": "not-found",
5 "reason": "The user badge progress progress123 was not found."
6}
7
GET /api/v1/user-badge-progress/user/:userId
此端點允許您透過使用者 ID 擷取該使用者的徽章進度紀錄。
Example Request:
GET 請求範例
Copy Run
Run 1
2curl -X GET "https://fastcomments.com/api/v1/user-badge-progress/user/user456?tenantId=demo&API_KEY=DEMO_API_SECRET"
3
Example Response:
回應
Copy
1
2{
3 "status": "success",
4 "userBadgeProgress": {
5 "id": "progress123",
6 "tenantId": "tenant001",
7 "userId": "user456",
8 "firstCommentId": "comment789",
9 "firstCommentDate": 1650532511000,
10 "autoTrustFactor": 0.75,
11 "progress": {
12 "0": 42,
13 "1": 120,
14 "2": 15,
15 "3": 3,
16 "5": 5,
17 "6": 1800000,
18 "8": 0,
19 "7": 0
20 }
21 }
22}
23
Possible Error Responses:
錯誤：缺少租戶 ID
Copy
1
2{
3 "status": "failed",
4 "code": "missing-tenant-id",
5 "reason": "Tenant ID (query param: tenantId) is missing."
6}
7
錯誤：缺少使用者 ID
Copy
1
2{
3 "status": "failed",
4 "code": "missing-user-id",
5 "reason": "The User ID (path param: userId) is missing."
6}
7
錯誤：未找到
Copy
1
2{
3 "status": "failed",
4 "code": "not-found",
5 "reason": "No badge progress found for user user456 in tenant tenant001."
6}
7
總結
我們希望您覺得我們的 API 文件詳盡且易於理解。如果您發現任何缺漏，請在下方告知我們。