FastComments API
FastComments 提供用于与多个资源交互的 API。可与我们的平台构建集成，或构建您自己的客户端！
在本文档中，您将找到 API 支持的所有资源的文档及其请求和响应类型。
对于企业客户，所有 API 访问都会记录在审核日志中。
生成的 SDK
FastComments 现在从我们的代码生成了一个 API 规范（尚未完成，但包含许多 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 密钥 作为 X-API-KEY 请求头或 API_KEY 查询参数传递来完成。您在调用 API 时还需要 tenantId。可以从与您的 api key 相同的页面检索到它。
安全提示
这些路由应从 服务器 调用。 切勿 从浏览器调用它们。这样会暴露您的 API 密钥——任何能查看页面源代码的人都将获得对您帐户的完全访问权限！
身份验证选项一 - 请求头
- 请求头：
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
响应：
统计不同值 响应
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
响应：
求和值 响应
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
响应：
平均值 响应
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
响应：
最小/最大值 响应
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
响应：
统计唯一值 响应
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
响应：
查询创建 响应
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
响应：
统计待审核评论 响应
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
响应：
评论分类统计 响应
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
以下资源可被聚合：
- 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
审计日志结构
一个 AuditLog 对象表示为具有此功能访问权限的租户审计的事件。
AuditLog 对象的结构如下：
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 读取它。
审计日志中的事件在两年后过期。
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 /** 评论者的姓名。始终必填。如果不可用，请设置为类似“匿名”的值。 **/
20 commenterName: string
21 /** 评论留存的日期，UTC 纪元时间。 **/
22 date: number
23 /** 评论的“显示标签”——例如 “Admin”、“Moderator” 或类似 “VIP User”。 **/
24 displayLabel?: string
25 /** 发布该评论的域名。 **/
26 domain?: string
27 /** 只读：该评论被举报的次数。 **/
28 flagCount?: number
29 /** 评论中成功解析的 #hashtags。你也可以手动添加标签以便查询，但它们不会自动在评论文本中显示。 **/
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 /** 评论使用的语言环境。如果未提供，将从 HTTP 的 Accept-Language 头部推断。 **/
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 /** 可选的与评论关联的元数据。 **/
66 meta?: Record<string, string | number | boolean>
67 /** 与此评论关联的可选版务组 ID 列表。 **/
68 moderationGroupIds?: string[]|null
69 /** 只读：对应当前用户（contextUserId）对该评论的投票对象的 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 /** 评论的“声望”（= 点赞数 - 点踩数）。 **/
98 votes?: number
99}
100
其中一些字段标注为 READONLY —— 这些字段由 API 返回，但无法设置。
评论文本结构
评论采用 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 = SSO 用户。 **/
10 type: 'user'|'sso'
11 /** 即使用户选择不接收通知，该字段仍会被设置为 true。 **/
12 sent: boolean
13}
14
话题标签
当使用的 hashtag 被成功解析时，信息会存储在名为 hashTags 的列表中。该列表中的每个对象具有以下结构。如果设置了 retain，也可以将话题标签手动添加到评论的 hashTags 数组中以便查询。
评论话题标签对象
Copy Run
Run 1
2interface CommentHashTag {
3 /** 话题标签 ID。 **/
4 id: string
5 /** 最终的 #hashtag 标签文本，包括 # 符号。 **/
6 tag: string
7 /** 如果该话题标签关联了自定义 URL，则会定义此字段。 **/
8 url?: string
9 /** 指在更新评论时是否应保留该话题标签，即使它不出现在评论文本中。用于在不更改评论文本的情况下标记评论。 **/
10 retain?: boolean
11}
12
GET /api/v1/comments
Resource: Comment as GET /api/v1/comments Credit Cost: 1
此 API 用于获取要向用户显示的评论。例如，它会自动过滤掉未批准或垃圾评论。
分页
分页可以根据性能需求和用例通过两种方式之一完成：
- 最快：预计算分页（Precalculated Pagination）：
- 当您使用我们预构建的小部件和客户端时，这就是 FastComments 的工作方式。
- 单击“下一页”仅会增加页数。
- 您可以将其视为通过键值存储检索。
- 用这种方式，只需定义从
0开始的page参数和作为direction的排序方向。 - 页面大小可以通过自定义规则进行调整。
- 最灵活：灵活分页（Flexible Pagination）：
- 在这种方式中，您可以定义自定义的
limit和skip参数。不要传递page。 - 也支持排序
direction。 limit是在应用了skip后要返回的总数量。- 示例：当页面大小 = 100 且
page = 2时，设置skip = 200, limit = 100。
- 示例：当页面大小 = 100 且
- 子评论仍计入分页。您可以使用
asTree选项绕过此问题。- 您可以通过
limitChildren和skipChildren对子评论进行分页。 - 您可以通过
maxTreeDepth限制返回的线程深度。
- 您可以通过
- 在这种方式中，您可以定义自定义的
线程（Threads）
- 使用
Precalculated Pagination时，评论按页面分组，线程中的评论会影响整个页面。- 这样，线程可以基于客户端的
parentId来确定。 - 例如，在一个页面中有一个顶级评论和 29 个回复，并在 API 中设置
page=0—— 您将只获得顶级评论和这 29 个子评论。 - 示例图，说明多页。
- 这样，线程可以基于客户端的
- 使用
Flexible Pagination时，您可以定义parentId参数。- 将其设置为 null 以仅获取顶级评论。
- 然后要查看线程，请再次调用 API 并传递
parentId。 - 一个常见的解决方案是对顶级评论进行一次 API 调用，然后并行调用 API 以获取每个评论的子评论。
- 新功能（截至 2023 年 2 月）! 使用
&asTree=true作为树来获取。- 您可以将其视为“作为树的灵活分页（Flexible Pagination as a Tree）”。
- 只有顶级评论计入分页。
- 将
parentId=null设置为从根开始树（您必须设置parentId）。 - 设置
skip和limit以进行分页。 - 将
asTree设置为true。 - 信用点成本增加
2x，因为在这种情况下我们的后端需要做更多工作。 - 根据需要设置
maxTreeDepth、limitChildren和skipChildren。
树说明
在使用 asTree 时，理解分页可能会很困难。这里有一张便捷的图示：
Tree Pagination Diagram
在用户上下文中获取评论
/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 /** The urlId (page url, or article id) the comments are associated with. **/
6 urlId?: string
7 /** Limit the comments returned by this user. **/
8 userId?: string
9 /** Use this to search by hashtag. To drill down to the intersection of multiple hashtags, do &hashTag=a&hashTag=b. **/
10 hashTag?: string
11 /** The sort direction. Default is MR (Most Relevant). Other options are OF (Oldest First) and NF (Newest First). **/
12 direction?: 'MR' | 'OF' | 'NF'
13 /** Precalculated Pagination: The page to fetch, starting with 0. Pass -1 for all comments (up to 250). **/
14 page?: number
15 /** Flexible Pagination: How many comments should we return? **/
16 limit?: number
17 /** Flexible Pagination: How many child comments should we return for each parent? **/
18 limitChildren?: number
19 /** Flexible Pagination: How many comments should we skip? **/
20 skip?: number
21 /** Flexible Pagination: How many child comments should we skip for each parent? **/
22 skipChildren?: number
23 /** For determining blocked and flagged comments. **/
24 contextUserId?: string
25 /** For determining blocked and flagged comments. **/
26 anonUserId?: string
27 /** For fetching child comments. **/
28 parentId?: string
29 /** For fetching as a tree. **/
30 asTree?: boolean
31 /** How far into the tree should we return data? 0 returns no children. 1 returns immediate children, etc. **/
32 maxTreeDepth?: number
33}
34
响应
评论响应结构
Copy
1
2interface CommentsResponse {
3 status: 'success' | 'failed'
4 /** Included on failure. **/
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 /** Included on failure. **/
7 reason?: string
8 /** The comments! **/
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 端点提供创建评论的功能。
常见用例包括自定义 UI、集成或导入。
注意：
- 如果需要，此 API 可以将评论小部件实时更新（这会将
creditsCost从1增加到2）。 - 如果提供了电子邮件地址，此 API 会在我们的系统中自动创建用户对象。
- 尝试保存两个电子邮件不同但用户名相同的评论，会导致第二条评论出现错误。
- 如果您指定了
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 的评论小部件实例的用户“实时”显示。注意：会将信用点消耗从 1 翻倍为 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 更新的评论仍可以在需要时进行垃圾邮件检查。
- 通过自定义规则管理页面配置的设置（例如最大评论长度）也会在此适用。
- 要允许用户更新评论文本，只需在请求体中指定
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 端点提供删除评论的功能。
Notes:
- 如果需要，此 API 可以实时更新评论小部件（这会将
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 的评论小部件的查看者进行“实时”删除。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 端点提供为特定用户标记评论的功能。
Notes:
- 此调用必须始终在用户上下文中进行。该用户可以是 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 用户、SSO 用户或租户用户。
- 在评论被自动取消批准（隐藏）后——该评论只能由管理员或版主重新批准。取消标记不会重新批准该评论。
取消评论标记 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
对于匿名标记，我们必须指定 anonUserId。这可以是表示匿名会话的 ID，或一个随机 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 的 body 参数，用于在执行此操作后检查客户端上是否有任何其他可能可见的评论应被封锁/解封。
Notes:
- 此调用必须始终在某个用户的上下文中进行。该用户可以是 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 请求体参数，用于在执行此操作后检查客户端上其他可能可见的评论是否应被封禁/解封。
注意：
- 此调用必须始终在用户上下文中进行。该用户可以是 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/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（不是 emailTemplateId）获取单个 EmailTemplate。
按 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仅在你有不同域名，或想为测试使用特定模板（例如将domain设置为localhost）时才相关。 - 如果你确实指定了
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
该路由用于通过 id 删除单个 EmailTemplate。
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 对象表示用户可以留下的标签。HashTags 可用于链接到外部内容或
将相关评论联系在一起。
The structure for the HashTag object is as follows:
HashTag 结构
Copy
1
2interface HashTag {
3 /** 应以 "#" 或所需的字符开头。 **/
4 tag: string
5 /** 可选的 URL，话题标签可以指向它。UI 在点击时不会按话题标签过滤评论，而是重定向到此 URL。 **/
6 url?: string
7 /** 只读 **/
8 createdAt: string
9}
10
Notes:
- In some API endpoints you will see that the hashtag is used in the URL. Remember to URI-Encoded values. For example,
#should instead be represented as%23. - Some of these fields are marked
READONLY- these are returned by the API but cannot be set.
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 /** 在失败时包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
6 /** 在失败时包含。 **/
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
版主结构
Moderator 对象表示版主的配置。
有三种类型的版主：
- 拥有
isCommentModeratorAdmin标志的管理员用户。 - 拥有
isCommentModeratorAdmin标志的 SSO 用户。 - 普通评论者，或被邀请为版主的 FastComments.com 用户。
Moderator 结构用于表示用例 3 的审核状态。
如果您想通过 API 邀请用户成为版主，请使用 Moderator API，创建一个 Moderator 并邀请他们。
如果用户没有 FastComments.com 帐户，邀请邮件会帮助他们完成设置。如果他们已有帐户，他们将
被授予对您租户的审核访问权限，并且 Moderator 对象的 userId 会更新为指向他们的用户。您将无法通过 API
访问他们的用户，因为在这种情况下该用户属于他们自己并由 FastComments.com 管理。
如果您需要完全管理该用户的帐户，我们建议使用 SSO，或将他们添加为 Tenant User 并
然后添加一个 Moderator 对象来跟踪他们的统计信息。
Moderator 结构可作为用例 1 和 2 的统计跟踪机制。创建用户后，添加一个定义了其 userId 的 Moderator
对象，其统计信息将会在 Comment Moderators Page 上被跟踪。
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。
Moderator 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
Moderator PATCH 请求结构
Copy
1
2interface ModeratorPatchQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
Moderator 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：
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 的功能。
向 Moderator 发送邀请邮件时存在以下限制：
Moderator必须已存在。fromName长度不得超过100 characters。
注意：
- 如果具有所提供电子邮件的用户已存在，他们将被邀请来管理您租户的评论。
- 如果具有所提供电子邮件的用户不存在，邀请链接将引导他们完成创建他们的账户的流程。
- 邀请将在
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
这将发送一封类似于 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
通知计数结构
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
通知结构
一个 Notification 对象表示针对用户的通知。
Notification 对象是自动创建的，无法通过 API 创建。它们在一年后会过期。
通知不能被删除。但可以更新将 viewed 设为 false，并且可以按 viewed 查询。
用户也可以通过将通知中的 optedOut 设置为 true 来选择不接收针对特定评论的通知。将其设置为 false 可以重新选择接收。
存在不同的通知类型 —— 请检查 relatedObjectType 和 type。
通知的创建方式非常灵活，可由多种情景触发（参见 NotificationType）。
截至目前，Notification 的存在并不意味着会或应该发送电子邮件。相反，通知用于通知提要和相关集成。
Notification 对象的结构如下：
Notification 对象结构
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 /** 使用 SSO 时，用户 id 的格式为 `<tenant id>:<user id>`。 **/
31 userId?: string
32 /** 在使用 SSO 时，你只需关心 `userId`。 **/
33 anonUserId?: string
34 /** urlId 几乎总是已定义。它仅在租户级通知（不常见）中为可选。 **/
35 urlId?: string
36 /** URL 被缓存以便快速导航到通知来源。 **/
37 url?: string
38 /** 页面标题被缓存以便快速查看通知来源。 **/
39 pageTitle?: string
40 relatedObjectType: NotificationObjectType
41 /** 例如，评论 id。 **/
42 relatedObjectId: string
43 viewed: boolean
44 createdAt: string // 日期字符串
45 type: NotificationType
46 fromCommentId?: string
47 fromVoteId?: string
48 /** fromUserName 和 fromUserAvatarSrc 在此处被缓存以便快速显示通知。用户更新时它们也会更新。 **/
49 fromUserName: string
50 fromUserId: string
51 fromUserAvatarSrc?: string
52 /** 将此设置为 true 以停止接收该对象的通知。 **/
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
通知 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
通知 PATCH 请求结构
Copy
1
2interface NotificationPatchQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
通知 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
页面结构
A Page 对象表示许多评论可能属于的页面。此关系由
urlId 定义。
A 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 对象中的某些参数会自动更新。这些是 counts 和 title 属性。Counts 不能通过 API 更新，因为它们是计算得出的值。页面的 title 可以通过 API 设置，但如果评论小部件在具有相同 urlId 但不同页面标题的页面上使用，则会被覆盖。
POST /api/v1/pages
Resource: Page as POST /api/v1/pages Credit Cost: 1
此 API 端点提供创建页面的功能。
一个常见的用例是访问控制。
注意：
- 如果您已经在评论线程中发表评论，或调用 API 创建了一个
Comment，您已经创建了一个Page对象！您可以尝试通过/by-url-idPage路由获取它，传入与评论小部件相同的urlId。 Page结构包含一些 计算得出 的值。当前这些是commentCount和rootCommentCount。它们会自动填充，不能由 API 设置。尝试设置这些值会导致 API 返回错误。
页面 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 事件结构
一个 PendingWebhookEvent 对象表示一个处于排队等待中的 webhook 事件。
PendingWebhookEvent 对象会自动创建，不能通过 API 手动创建。它们也会在一年后过期。
可以删除它们，从而将任务从队列中移除。
存在不同的事件类型 —— 请检查 eventType (OutboundSyncEventType) 和 type (OutboundSyncType)。
此 API 的一个常见用例是实现自定义监控。你可能希望定期调用 /count 端点，以轮询给定筛选器下的未完成数量。
PendingWebhookEvent 对象的结构如下：
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 /** 事件发生时的 comment 对象。我们从 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
此路由返回一个待处理的 webhook 事件列表，包含在 pendingWebhookEvents 参数中。
此 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 provides an easy to use SSO solution. Updating a user's information with the HMAC-based integration is as simple as having the user load the page with an updated payload.
但是，可能希望在该流程之外管理用户，以提高应用程序的一致性。
The SSO User API provides a way to CRUD objects that we call SSOUsers. These objects are different from regular Users and kept separate for type safety.
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
Billing for SSO Users
SSO users are billed differently based on their permission flags:
- Regular SSO Users: Users without admin or moderator permissions are billed as regular SSO users
- SSO Admins: Users with
isAccountOwnerorisAdminAdminflags are billed separately as SSO Admins (same rate as regular tenant admins) - SSO Moderators: Users with
isCommentModeratorAdminflag are billed separately as SSO Moderators (same rate as regular moderators)
Important: To prevent double billing, the system automatically deduplicates SSO users against regular tenant users and moderators by email address. If an SSO user has the same email as a regular tenant user or moderator, they will not be billed twice.
SSO 用户的计费
根据权限标志，SSO 用户的计费方式不同：
- 常规 SSO 用户：没有管理员或版主权限的用户按常规 SSO 用户计费
- SSO 管理员：具有
isAccountOwner或isAdminAdmin标志的用户将作为 SSO 管理员单独计费（与常规租户管理员费率相同） - SSO 版主：具有
isCommentModeratorAdmin标志的用户将作为 SSO 版主单独计费（与常规版主费率相同）
重要：为防止重复计费，系统会根据电子邮件地址自动对 SSO 用户与常规租户用户和版主进行去重。如果 SSO 用户与常规租户用户或版主的电子邮件相同，则不会被重复计费。
Access Control
Users can be broken into groups. This is what the groupIds field is for, and is optional.
访问控制
用户可以被划分为组。这就是 groupIds 字段的用途，且为可选。
@Mentions
By default @mentions will use username to search for other sso users when the @ character is typed. If displayName is used, then results matching
username will be ignored when there is a match for displayName, and the @mention search results will use displayName.
@提及
默认情况下，当输入 @ 字符时，@mentions 将使用 username 来搜索其他 SSO 用户。如果使用 displayName，当有与 displayName 匹配时，
与 username 匹配的结果将被忽略，@mention 搜索结果将使用 displayName。
Subscriptions
With FastComments, users can subscribe to a page by clicking the bell icon in the comment widget and clicking Subscribe.
With a regular user, we send them notification emails based on their notification settings.
With SSO Users, we split this up for backwards compatibility. Users will only get sent these additional subscription notification
emails if you set optedInSubscriptionNotifications to true.
订阅
在 FastComments 中，用户可以通过在评论小部件中点击铃铛图标并选择订阅来订阅页面。
对于常规用户，我们会根据他们的通知设置向其发送通知电子邮件。
对于 SSO 用户，我们为向后兼容而进行了拆分。只有当您将 optedInSubscriptionNotifications 设置为 true 时，用户才会收到这些额外的订阅通知
电子邮件。
Badges
You can assign badges to SSO users using the badgeConfig property. Badges are visual indicators that appear next to a user's name in comments.
badgeIds- An array of badge IDs to assign to the user. These must be valid badge IDs created in your FastComments account. Limited to 30 badges.override- If true, all existing badges displayed on comments will be replaced with the provided ones. If false or omitted, the provided badges will be added to any existing badges.update- If true, badge display properties will be updated from the tenant configuration whenever the user logs in.
徽章
您可以使用 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 用户。
SSOUser 按 ID 的 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 用户。
按邮箱获取 SSOUser 的 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
Integration Note
通过 API 传递的数据可以通过传递不同的 SSO 用户 HMAC 有效负载来覆盖。例如, if you set a username via the API, but then pass a different one via the SSO flow on page load, we will automatically update their 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 用户。
请注意，如果使用该用户的有效负载重新加载评论小部件，系统会无缝地重新创建该用户。
可以通过查询参数 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。这些可以通过小部件自定义界面进行自定义。
示例
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 以同时删除该用户的评论。 这会使消耗的 credits 翻倍。 **/
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
订阅结构
A Subscription object 表示用户的订阅。
Subscription objects 在用户在评论小部件中点击通知铃铛并点击 "订阅此页面" 时创建。
Subscriptions 也可以通过 API 创建。
Having a Subscription object causes Notification objects to be generated, and emails sent, when new comments are left on the root of the associated page
that the Subscription is for. 电子邮件的发送取决于用户类型。对于普通用户，这取决于 optedInNotifications。对于 SSO 用户，这取决于 optedInSubscriptionNotifications。注意，有些应用可能没有可通过 Web 访问的页面的概念，在这种情况下，只需将 urlId 设置为您要订阅的项目的 id（与传递给评论小部件的 urlId 值相同）。
The structure for the Subscription object is as follows:
订阅结构
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 个按 createdAt 排序的 Subscription 对象，最新的在前。
您可以按 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
订阅 请求 结构
Copy
1
2interface SubscriptionsGetQueryParams {
3 tenantId: string
4 API_KEY: string
5 /** 通过跳过记录进行分页。 **/
6 skip?: number
7 /** 按用户过滤。 **/
8 userId?: string
9}
10
订阅 响应 结构
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 对象。
订阅 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
订阅 POST 请求结构
Copy
1
2interface SubscriptionPostQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
订阅 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
租户每日使用量结构
一个 TenantDailyUsage 对象表示租户在某一天的使用情况。如果在某租户的某个给定
天没有活动，则该天将不会有 TenantDailyUsage 对象。
The TenantDailyUsage object is 不是 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 /** 从 0 开始。基于 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 创建它们。白标租户
不能创建其他白标租户（只允许一层嵌套）。
The structure for the Tenant object is as follows:
租户结构
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 排序。
费用基于返回的租户数量，按 1 credit per 10 租户计费。
租户 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 编码作为查询参数进行过滤：
按 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
租户 请求 结构
Copy
1
2interface TenantsRequestQueryParams {
3 tenantId: string
4 API_KEY: string
5 /** 用于分页要跳过的租户数量。 **/
6 skip?: number
7 /** 按 meta 参数过滤。 **/
8 meta?: string
9}
10
租户 响应 结构
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查询参数，该参数是启用白标的parent tenant的 id。
我们只需少量参数即可创建一个 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
租户创建 请求结构
Copy
1
2interface TenantPostQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
租户创建 响应结构
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
租户套餐结构
TenantPackage 定义了可供 Tenant 使用的套餐信息。一个租户可能有多个可用的套餐，但在任意时刻只有一个处于使用中。
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。
按 ID 获取 TenantPackage 的 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 排序。
计费基于返回的 tenant packages 数量，计费为 1 credit per 10 个 tenant packages。
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 通过电子邮件的 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 密钥等。
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。
TenantUser 按 ID 的 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 排序。
费用基于返回的租户用户数量计算，每返回 10 个租户用户消耗 1 积分。
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 后过期。
发送登录链接到 TenantUser 时存在以下限制：
TenantUser必须已存在。- 您必须有权限管理该
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必须在 Supported Locales 列表中。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 /** 在失败时包含。 **/
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 作为评论内容。这些可以通过小部件自定义界面进行定制。
示例
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 是表示所有用户的最通用属性的对象。
请记住，在 FastComments 中，我们有多种不同的用户使用场景：
- Secure SSO
- Simple SSO
- Tenant Users (例如：管理员)
- Commenters
This API is for Commenters and users created via Simple 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
投票结构
A 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 的 登录以投票 机制时，会创建这些投票。
- 匿名投票，会应用到相应的评论。这些与匿名评论一起创建。
为了减少混淆，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
Votes 请求结构
Copy
1
2interface VotesRequestQueryParams {
3 tenantId: string
4 API_KEY: string
5 urlId: string
6}
7
Votes 响应结构
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 /** Included on failure. **/
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 /** Included on failure. **/
7 reason?: string
8 voteId?: string
9}
10
创建匿名投票
可以通过在查询参数中设置 anonUserId 而不是 userId 来创建匿名投票。
该 id 不必与任何地方的用户对象对应（因此为匿名）。它只是会话的一个标识符 for the session, so you can fetch votes again in the same session, to check if a comment has been voted.
如果您没有像 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 /** 与此域相关的徽标。用于电子邮件。请使用 HTTPS。 **/
12 logoSrc?: string
13 /** 与此域相关的较小徽标。请使用 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 界面移除域将删除通过该界面为该域添加的任何对应配置。
用于电子邮件自定义
电子邮件页脚中的退订链接以及许多邮件客户端提供的一键退订功能，可以通过此 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
单个 DomainConfigs 可通过其对应的 domain 获取。
按域名的域配置 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
按域名的域配置请求结构
Copy
1
2interface DomainConfigsByDomainRequestQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
按域名的域配置响应结构
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。
按 ID 获取 QuestionConfig 的 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 Structure
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 Update cURL Example
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 Update Request Structure
Copy
1
2interface QuestionConfigPatchQueryParams {
3 tenantId: string
4 API_KEY: string
5}
6
QuestionConfig Update Response Structure
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。
按 ID 获取 QuestionResult 的 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 /** 注意 - 当未指定 timeBucket 时为 null。 **/
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
以下是可用于聚合的查询参数：
QuestionResultsAggregation 请求结构
Copy
1
2interface QuestionResultsAggregateRequestQueryParams {
3 tenantId: string
4 API_KEY: string
5 /** 您可以对一个或多个问题的结果进行聚合。 **/
6 questionId: string | string[]
7 startDate?: string | number
8 timeBucket?: 'day' | 'month' | 'year'
9 /** 针对特定页面进行聚合。 **/
10 urlId?: string
11 /** 针对特定用户进行聚合。 **/
12 userId?: string
13 /** 强制立即重新计算并更新缓存。 **/
14 forceRecalculate?: boolean
15}
16
下面是一个示例请求：
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
示例响应：
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 /** 失败时包含。 **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
6 /** 失败时包含。 **/
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 /** 此徽章的创建时间（自纪元以来的毫秒） */
12 createdAt?: number
13 /** 用户收到此徽章的时间（自纪元以来的毫秒） */
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
此端点允许您根据各种条件获取用户徽章。
示例请求：
GET 请求示例
Copy Run
Run 1
2curl -X GET "https://fastcomments.com/api/v1/user-badges?tenantId=demo&API_KEY=DEMO_API_SECRET"
3
您可以添加各种查询参数来过滤结果：
userId- 获取特定用户的徽章badgeId- 获取特定徽章的实例type- 按徽章类型筛选 (0=CommentCount, 1=CommentUpVotes, 2=CommentReplies, etc. See UserBadge structure for full list)displayedOnComments- 按徽章是否显示在评论中筛选 (true/false)limit- 返回的徽章最大数量（默认 30，最大 200）skip- 要跳过的徽章数量（用于分页）
示例响应：
响应
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
可能的错误响应：
错误：缺少 Tenant 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
此端点允许您创建新的用户徽章分配。
示例请求：
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
请求体必须包含以下参数：
userId(required) - 要分配徽章的用户 IDbadgeId(required) - 要分配的徽章 IDdisplayedOnComments(optional) - 徽章是否应显示在用户的评论上（默认为 true）
重要说明：
- 徽章必须存在于您的租户徽章目录中并已启用
- 您只能将徽章分配给属于您的租户的用户或在您的网站上发表评论的用户
响应示例：
响应
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
错误：缺少用户 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
This endpoint allows you to update a user badge assignment.
Currently, the only property that can be updated is displayedOnComments, which controls whether the badge is displayed on the user's comments.
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 /** 用户第一条评论的日期（自纪元以来的毫秒数） */
12 firstCommentDate?: number
13 /** 基于用户活动自动计算的信任因子 */
14 autoTrustFactor?: number
15 /** 由管理员手动设置的信任因子 */
16 manualTrustFactor?: number
17 /** 包含各种指标的详细进度对象，键与 BadgeType 枚举匹配 */
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 获取该用户的徽章进度记录。
示例请求：
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
示例响应：
响应
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
错误：缺少用户 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 文档详尽且易于理解。如果您发现任何遗漏，请在下方告诉我们。