API за живи коментари

Използване на ресурси

Трябва да се отбележи, че извличането на данни от API се брои като използване във вашия акаунт.

Всеки ресурс ще изброи това използване в своя собствен раздел.

Някои ресурси струват повече за обслужване от други. Всеки крайна точка има зададена цена в кредити за API повикване. За някои крайни точки броят на кредитите варира в зависимост от опциите и размерите на отговора.

Използването на API може да се провери на страницата Billing Analytics и се актуализира на всеки няколко минути.

Забележка!

Препоръчваме първо да прочетете документацията за Pages, за да намалите объркването при определяне какви стойности да предадете за urlId в Comment API.

Уебкуки

Абонаментите за уебкуки имат собствено ръководство. POST, GET и DELETE /api/v1/webhooks, както и GET /api/v1/webhooks/sample-payloads, са документирани в Managing Subscriptions via API, а натоварванията на събитията – в Webhook Structures.

FastComments е сървър за упълномощаване OAuth 2.1. Приложение може да получи токен, който е свързан с един FastComments акаунт и да го използва за всеки крайна точка в това ръководство вместо API ключ. По този начин Zapier приложението, MCP сървърът и други интеграции от трети страни се свързват.

Токените се издават чрез потока за код за упълномощаване с PKCE. Няма клиентски идентификационни данни или имплицитно предоставяне.

Откриване

Местоположенията на крайните точки, поддържаните предоставяния и методи за упълномощаване се публикуват на стандартния URL за метаданни:

Метаданни на сървъра за упълномощаване

Copy

1

2https://fastcomments.com/.well-known/oauth-authorization-server

3

Крайните точки, които описва:

OAuth крайни точки

Copy

1

2GET https://fastcomments.com/oauth/authorize

3POST https://fastcomments.com/oauth/token

4POST https://fastcomments.com/oauth/revoke

5POST https://fastcomments.com/oauth/register

6

Акаунтите в регион EU използват https://eu.fastcomments.com като издател, със същите пътища.

Регистриране на клиент

Клиентът се нуждае от client_id и регистриран redirect_uri, преди да може да започне потока. Има два начина да се получи такъв:

• Динамична регистрация на клиент. POST /oauth/register с JSON тяло според RFC 7591 (redirect_uris, client_name, client_uri, logo_uri, token_endpoint_auth_method). Отговорът съдържа client_id и, за поверителни клиенти, client_secret. Регистрацията е неаутентицирана и има ограничение за честота по IP.
• Документ с метаданни за клиентски идентификатор. Клиентът използва https URL, който контролира, като свой client_id. FastComments извлича този URL и чете същите полета за метаданни от него. Не е необходима заявка за регистрация.

Партньорски приложения, изброени в таблото на FastComments, като Zapier, се регистрират директно от FastComments. Свържете се с поддръжката, ако създавате листинг в пазар и ви е нужен клиент от първа страна.

Обхвати

Обхвати

Copy

1

2read GET and HEAD requests

3write every other method

4

Заявка, която не изисква обхват, получава и двете. Потребителят вижда заявените обхвати на страницата за съгласие. Заявка за обхват, различен от тези два, се отказва с invalid_scope.

Стъпка 1 – Заявка за упълномощаване

Пренасочете браузъра на потребителя към крайната точка за упълномощаване. PKCE с метод S256 е задължителен за всеки клиент.

Заявка за упълномощаване

Copy

1

2GET https://fastcomments.com/oauth/authorize

3 ?response_type=code

4 &client_id=YOUR_CLIENT_ID

5 &redirect_uri=https://example.com/oauth/callback

6 &scope=read%20write

7 &state=RANDOM_STATE

8 &code_challenge=BASE64URL_SHA256_OF_VERIFIER

9 &code_challenge_method=S256

10

Параметри на заявката за упълномощаване

Copy

1

2interface OAuthAuthorizeQueryParams {

3 response_type: 'code'

4 client_id: string

5 /** Трябва точно да съвпада с един от регистрираните за клиента URI за пренасочване. **/

6 redirect_uri: string

7 /** Разделени с интервал. Пропуснете, за да поискате и двата обхвата. **/

8 scope?: 'read' | 'write' | 'read write'

9 /** Връща се непроменено в пренасочването. Използвайте го, за да свържете обратния повик към сесията, която стартира потока. **/

10 state?: string

11 /** base64url(sha256(code_verifier)). **/

12 code_challenge: string

13 code_challenge_method: 'S256'

14 /** Незадължителен индикатор за ресурс според RFC 8707. Ако се изпрати, същата стойност трябва да се изпрати към крайната точка за токен. **/

15 resource?: string

16}

17

Потребителят се вписва в FastComments, ако е необходимо, и вижда страница за съгласие, която назовава вашето приложение, акаунта, към който ще се свърже, и заявените обхвати. Потребителят трябва да притежава правото API Admin за този акаунт; всеки друг ще види грешка за разрешения вместо формуляра за съгласие. Одобряването пренасочва браузъра към вашия redirect_uri с code и state. Отказът пренасочва с error=access_denied.

Кодът за упълномощаване е валиден 10 минути и може да се обменя веднъж. Вторият обмен на същия код отмяна всеки токен, създаден от първия обмен.

Стъпка 2 – Заявка за токен

Разменете кода за токени. Тялото е форм-енкодирано. Поверителните клиенти се удостоверяват с client_secret_basic (HTTP Basic) или client_secret_post (секрет в тялото). Публичните клиенти изпращат само client_id.

Пример за cURL заявка за токен

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/oauth/token' \

4 --header 'Content-Type: application/x-www-form-urlencoded' \

5 --data 'grant_type=authorization_code' \

6 --data 'client_id=YOUR_CLIENT_ID' \

7 --data 'client_secret=YOUR_CLIENT_SECRET' \

8 --data 'code=fcac_...' \

9 --data 'code_verifier=YOUR_PKCE_VERIFIER' \

10 --data 'redirect_uri=https://example.com/oauth/callback'

11

Тяло на заявка за токен (authorization_code)

Copy

1

2interface OAuthTokenRequestAuthorizationCode {

3 grant_type: 'authorization_code'

4 client_id: string

5 /** Само за поверителни клиенти. Може да се изпрати като HTTP Basic удостоверяване вместо това. **/

6 client_secret?: string

7 code: string

8 code_verifier: string

9 /** Трябва да съвпада с заявката за упълномощаване, когато се изпрати. **/

10 redirect_uri?: string

11 resource?: string

12}

13

Структура на отговора за токен

Copy

1

2interface OAuthTokenResponse {

3 /** Префикс fcat_. Валиден за един час. **/

4 access_token: string

5 token_type: 'bearer'

6 /** Секунди до изтичане на токена за достъп. 3600. **/

7 expires_in: number

8 /** Префикс fcrt_. Валиден 30 дни от издаването. **/

9 refresh_token: string

10 /** Обхвати, разделени с интервал, предоставени. **/

11 scope: string

12}

13

Грешките следват RFC 6749: JSON тяло с error и error_description, HTTP 400 за invalid_request, invalid_grant, invalid_scope, invalid_target и unsupported_grant_type, HTTP 401 за invalid_client, HTTP 429 при ограничение на честотата.

Стъпка 3 – Извикване на API

Изпратете токена за достъп като носител токен. Наемателят се подразбира от токена, така че tenantId е незадължителен. Когато се предостави, трябва да съвпада с токена, иначе заявката се отказва.

Пример за cURL заявка с носител токен

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/me' \

4 --header 'Authorization: Bearer fcat_...'

5

GET /api/v1/me връща наемателя, упълномощаващия потребител и предоставените обхвати, което я прави подходяща за тест на връзка. Заявка с изтекъл или оттеглен токен получава HTTP 401. Заявка, чий метод изисква обхват, който токенът не притежава, получава HTTP 403.

Стъпка 4 – Обновяване

Пример за cURL заявка за обновяване

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/oauth/token' \

4 --header 'Content-Type: application/x-www-form-urlencoded' \

5 --data 'grant_type=refresh_token' \

6 --data 'client_id=YOUR_CLIENT_ID' \

7 --data 'client_secret=YOUR_CLIENT_SECRET' \

8 --data 'refresh_token=fcrt_...'

9

Тяло на заявка за токен (refresh_token)

Copy

1

2interface OAuthTokenRequestRefreshToken {

3 grant_type: 'refresh_token'

4 client_id: string

5 client_secret?: string

6 refresh_token: string

7 /** Незадължително. Ограничаване до подмножество от първоначално предоставените обхвати. **/

8 scope?: string

9 resource?: string

10}

11

Отговорът има същата структура като обмена на код. Токените за обновяване се въртят: всяко обновяване връща нов refresh_token и оттегля стария след 30‑секунден прозорец за едновременни заявки. Представянето на токен за обновяване, който е въртян преди повече от 30 секунди, се счита за повторно използване и оттегля цялото предоставяне. Партньорски приложения, регистрирани от FastComments, са изключени от въртенето и получават същия токен за обновяване с удължена валидност с още 30 дни.

Обновяването също проверява дали упълномощаващият потребител все още притежава API Admin за акаунта. Ако не, предоставянето се оттегля и отговорът е invalid_grant.

Отмяна

Пример за cURL заявка за отмяна

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/oauth/revoke' \

4 --header 'Content-Type: application/x-www-form-urlencoded' \

5 --data 'client_id=YOUR_CLIENT_ID' \

6 --data 'client_secret=YOUR_CLIENT_SECRET' \

7 --data 'token=fcrt_...' \

8 --data 'token_type_hint=refresh_token'

9

Отмяната на токен за обновяване отмяна всички токени за достъп, издадени от същото предоставяне. Отмяната на токен за достъп отмяна само този токен. Крайната точка връща HTTP 200 с празен JSON обект, независимо дали токенът е намерен, според RFC 7009.

Потребителите също могат да отмятат връзка от Свързани приложения в таблото на FastComments. Всеки токен за това приложение спира да работи незабавно.

Този 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/** An operation that will be applied on a field */

5export interface AggregationOperation {

6 /** The field to operate on */

7 field: string;

8 /** The type of operation */

9 op: AggregationOpType;

10 /** Optional alias for the output; if not provided, a default alias is computed */

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

Този API използва пагинация, предоставена от параметрите skip, limit, before и after. AuditLogs се връщат в страници по 1000 по подразбиране, до максимален limit от 10000, подредени по when и id. Страниците са големи, защото този крайна точка обикновено се използва за изтегляне на история, а не за интерактивно прелистване.

Всеки 100 върнати записи имат кредитна цена от 1.

По подразбиране ще получите списък с най-новите елементи първо. По този начин можете да правите заявки, започвайки с skip=0, прелистване, докато намерите последния запис, който сте консумирали.

Алтернативно, можете да сортирате от най-старите към най-новите и да прелиствате, докато не останат повече записи.

Сортирането може да се извърши, като зададете order на ASC или DESC. По подразбиране е DESC.

Запитване по дата е възможно чрез before и after като времеви печати в милисекунди. before и after НЕ са включващи и всяко от тях може да се използва самостоятелно.

Откриване какво се е случило с лице

Всяко събитие записва кой го е извършил (username, userId, ip) и, отделно, върху какво е извършено. targetLabel е четим за хора етикет за този обект, например jsmith (jsmith@example.com), а targetId е неговият идентификатор. Използвайте target за нечувствително към регистъра съвпадение на подниз в етикета, когато знаете името или имейла на лицето, но не неговия идентификатор.

Изтриванията запазват етикета по време на събитието, така че премахнат потребител или модератор все още може да бъде идентифициран след като основният запис е изтрит.

Управлявани наематели

Ако вашият наемател управлява други наематели, задайте includeManagedTenants=true, за да върнете събития от вашия наемател и всеки наемател, който той управлява, в един отговор. tenantId на всеки върнат запис ви казва от кой наемател е дошъл.

Пример cURL за AuditLog

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 AuditLogsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 order?: 'ASC' | 'DESC'

6 /** Max 10000. Defaults to 1000. **/

7 limit?: number

8 skip?: number

9 before?: number

10 after?: number

11 /** Only events performed by this username. **/

12 username?: string

13 /** Only events from this IP address. **/

14 ip?: string

15 /** Only events of this type. **/

16 crudType?: 'c' | 'r' | 'u' | 'd' | 'login'

17 /** Only events for this resource, e.g. User or Moderator. **/

18 resourceName?: string

19 /** Only events whose affected object has this id. **/

20 targetId?: string

21 /** Case-insensitive substring match on the affected object's label. **/

22 target?: string

23 /** Also return events from tenants this tenant manages. **/

24 includeManagedTenants?: boolean

25}

26

Структура на отговор за AuditLog

Copy

1

2interface AuditLogsResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'invalid-limit' | 'invalid-skip'

6 /** Included on failure. **/

7 reason?: string

8 /** The logs! **/

9 auditLogs: AuditLog[]

10}

11

Този маршрут връща пакетните задачи на наемателя от всички типове, най-новите първи, по 100 на страница. Използвайте type и status, за да стесните списъка, и skip, за да превъртате страниците.

Пример за cURL за списък на BatchJob

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/batch-jobs?tenantId=demo&API_KEY=DEMO_API_SECRET&type=migrate-pages&status=running'

4

Структура на заявка за списък на BatchJob

Copy

1

2interface BatchJobsQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Само задачи от този тип, например migrate-pages. **/

6 type?: string

7 status?: 'requested' | 'running' | 'success' | 'failed'

8 /** Колко задачи да се пропуснат, за странициране. Неотрицателно цяло число. **/

9 skip?: number

10}

11

Структура на отговор за списък на BatchJob

Copy

1

2interface BatchJobsResponse {

3 status: 'success' | 'failed'

4 /** Включено при неуспех. **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'invalid-skip' | 'internal'

6 /** Включено при неуспех. **/

7 reason?: string

8 /** Най-новите първи, най-много 100. **/

9 batchJobs?: BatchJob[]

10}

11

Този маршрут връща състоянието, напредъка и, след като завърши, резултата от една партидна задача. Използвайте го, за да следите задача, стартирана от POST /api/v1/pages/migrations или POST /api/v1/pages/migrations/:undoId/undo.

Задачата се счита за завършена, когато нейното status е success или failed. Всяко извикване струва 1 кредит, затова правете заявки на всеки няколко секунди, вместо непрекъснато.

BatchJob по Id cURL пример

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/batch-jobs/my-batch-job-id?tenantId=demo&API_KEY=DEMO_API_SECRET'

4

BatchJob по Id структура на заявка

Copy

1

2interface BatchJobQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

BatchJob по Id структура на отговор

Copy

1

2interface BatchJobResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'internal'

6 /** Included on failure. **/

7 reason?: string

8 batchJob?: BatchJob

9}

10

Пример за завършена миграция на страница

Copy

1

2{

3 "status": "success",

4 "batchJob": {

5 "id": "my-batch-job-id",

6 "type": "migrate-pages",

7 "status": "success",

8 "createdAt": "2026-10-19T16:00:00.000Z",

9 "completedAt": "2026-10-19T16:00:12.000Z",

10 "processedCount": 2,

11 "totalCount": 2,

12 "pageMigrationResults": [

13 {"from": "old-post-id", "to": "new-post-id", "type": "urlId", "status": "success", "commentsMigrated": 42},

14 {"from": "old.example.com", "to": "new.example.com", "type": "domain", "status": "success", "commentsMigrated": 1250}

15 ],

16 "undoId": "my-undo-id"

17 }

18}

19

Този API се използва за получаване на коментари за показване на потребител. Например, той автоматично филтрира неодобрените или спам коментари.

Пагинация

Пагинацията може да се извърши по един от двата начина, в зависимост от изискванията за производителност и случая на употреба:

1. Най-бързо: Предварително изчислена пагинация:
   1. Това е начинът, по който FastComments работи, когато използвате нашите предварително изградени уиджети и клиенти.
   2. Кликването върху „next“ просто увеличава броя на страниците.
   3. Можете да го разглеждате като извличано от хранилище с ключ-стойност.
   4. По този начин, просто задайте параметъра page, започвайки от 0, и посока на сортиране като direction.
   5. Размерите на страниците могат да се персонализират чрез правила за персонализация.
2. Най-гъвкаво: Гъвкава пагинация:
   1. По този начин можете да зададете персонализирани параметри limit и skip. Не предавайте page.
   2. Сортирането direction също се поддържа.
   3. limit е общият брой, който да се върне след прилагане на skip.
      • Пример: задайте skip = 200, limit = 100, когато page size = 100 и page = 2.
   4. Дъщерните коментари все още се броят в пагинацията. Можете да заобиколите това, като използвате опцията asTree.
      • Можете да пагинирате дъщерните чрез limitChildren и skipChildren.
      • Можете да ограничите дълбочината на върнатите нишки чрез maxTreeDepth.

Нишки

1. При използване на Precalculated Pagination, коментарите се групират по страница и коментарите в нишките влияят върху цялата страница.
   1. По този начин нишките могат да се определят от клиента въз основа на parentId.
   2. Например, при страница с един коментар от най-горно ниво и 29 отговора, и задаване на page=0 в API - ще получите само коментара от най-горно ниво и 29-те дъщерни.
2. При използване на Flexible Pagination, можете да зададете параметър parentId.
   1. Задайте го на null, за да получите само коментари от най-горно ниво.
   2. След това, за да видите нишките, извикайте отново API и предайте parentId.
   3. Често решение е да направите API заявка за коментарите от най-горно ниво и след това паралелни API заявки, за да получите коментари за дъщерните на всеки коментар.
3. НОВО От февруари 2023 г.! Извличане като дърво, използвайки &asTree=true.
   1. Можете да го разглеждате като Гъвкава пагинация като дърво.
   2. Само коментарите от най-горно ниво се броят в пагинацията.
   3. Задайте parentId=null, за да започнете дървото от корена (трябва да зададете parentId).
   4. Задайте skip и limit за пагинация.
   5. Задайте asTree на true.
   6. Цената в кредити се увеличава с 2x, тъй като нашият бекенд трябва да извърши много повече работа в този сценарий.
   7. Задайте maxTreeDepth, limitChildren и skipChildren според желанието.

Обяснение на дърветата

При използване на asTree, може да е трудно да се разбере пагинацията. Ето удобна графика:

Диаграма на пагинацията на дървото

Извличане на коментари в контекста на потребител

API‑т /comments може да се използва в два контекста, за различни случаи на употреба:

• За връщане на коментари, сортирани и маркирани с информация за изграждане на ваш собствен клиент.
  • В този случай, задайте параметъра за заявка 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

Вероятно искате да използвате API‑то Comment с параметъра urlId. Можете първо да извикате API‑то Pages, за да видите как изглеждат наличните за вас стойности на urlId.

Анонимни действия

За анонимно коментиране вероятно искате да предадете anonUserId, когато извличате коментари, и при извършване на маркиране и блокиране.

(!) Това е задължително за много магазини за приложения, тъй като потребителите трябва да могат да маркират съдържание, създадено от потребители, което виждат, дори ако не са влезли. Ако не го направите, вашето приложение може да бъде премахнато от съответния магазин.

Коментари, които не се връщат

Проверете дали вашите коментари са одобрени и не са спам.

Този 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 /** Included on failure. **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'missing-id'

6 /** Included on failure. **/

7 reason?: string

8 /** The comment! **/

9 comment?: Comment

10}

11

Тази API крайна точка предоставя възможност за създаване на коментари.

Често срещани случаи на употреба са персонализирани потребителски интерфейси, интеграции или импортиране.

Забележки:

• Този API може да актуализира уиджета за коментари "на живо" ако желаете (това увеличава creditsCost от 1 на 2).
• Този API автоматично ще създаде потребителски обекти в нашата система, ако е предоставен имейл.
• Опитът да запазите два коментара с различни имейли, но с едно и също потребителско име, ще доведе до грешка за втория коментар.
• Ако посочвате parentId и дъщерният коментар има notificationSentForParent като false, ние ще изпратим известия за родителския коментар. Това се прави на всеки час (групираме известията заедно, за да намалим броя на изпратените имейли).
• Ако искате да изпращате приветствени имейли при създаване на потребители или имейли за потвърждение на коментари, задайте sendEmails на true в параметрите на заявката.
• Коментарите, създадени чрез този API, ще се показват в страниците за анализ и модерация на административното приложение.
• "лошите думи" все още се маскират в имената на коментиращите и текста на коментарите, ако настройката е включена.
• Коментарите, създадени чрез този 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 /** Whether the comment should appear "live" to users viewing instances of the comment widget with the same urlId. NOTE: Doubles credit cost from 1 to 2. **/

7 isLive?: 'true' | 'false'

8 sendEmails?: 'true' | 'false'

9 populateNotifications?: 'true' | 'false'

10}

11

Структура на отговора за POST на коментар

Copy

1

2

3interface CommentPostResponse {

4 status: 'success' | 'failed'

5 /** Included on failure. **/

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 /** Included on failure. **/

8 reason?: string

9 /** The created comment. **/

10 comment?: Comment

11 /** The associated user, which may or may not have already existed. **/

12 user?: User

13}

14

Този API крайна точка предоставя възможност за обновяване на един коментар.

Забележки:

• Този API може да обнови уиджета за коментари "на живо", ако е желано (това увеличава базовия creditsCost от 1 на 2).
  • Това може да направи миграцията на коментари между страници "на живо" (промяна на urlId).
  • Миграциите струват допълнителни 2 кредита, тъй като страниците се изчисляват предварително и това натоварва процесора.
• За разлика от API за създаване, този API НЯМА автоматично да създава потребителски обекти в нашата система, ако е предоставен имейл.
• Коментарите, обновени чрез този API, все пак могат да бъдат проверявани за спам, ако е желано.
• Конфигурация като максимална дължина на коментара, ако е настроена чрез администраторската страница Customization Rule, ще се прилага и тук.
• За да позволите на потребителите да обновяват текста на своя коментар, можете просто да посочите comment в тялото на заявката. Ние ще генерираме получения commentHTML.
  • Ако дефинирате и comment, и commentHTML, няма да генерираме автоматично HTML-а.
  • Ако потребителят добави упоменания или хаштагове в новия си текст, те все пак ще бъдат обработени като при POST API-я.
• При обновяване на commenterEmail на коментар е най-добре да посочите и userId. В противен случай трябва да сте сигурни, че потребителят с този имейл принадлежи към вашия tenant, или заявката ще се провали.
• Ако целевият коментар е заключен (isLocked: true), заявката се отхвърля с code: 'locked'. Първо отключете коментара, обновете го, а след това го заключете отново, ако е желано.

Минимален пример за 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' | 'locked'

7 /** Включва се при неуспех. **/

8 reason?: string

9}

10

Тази API крайна точка предоставя възможност за изтриване на коментар.

Бележки:

• Този API може да актуализира коментарния widget "live" ако е желано (това увеличава creditsCost от 1 до 2).
• Този API ще изтрие всички дочерни коментари.
• Ако целевият коментар е заключен (isLocked: true), заявката се отхвърля с code: 'locked'. Първо отключете коментара, след което го изтрийте.

Пример на 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

Структура на DELETE заявка за коментар

Copy

1

2interface CommentDeleteQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Потребителят, извършващ актуализацията. При желание може да се използва за проверка дали може да изтрие коментара. **/

6 contextUserId?: string

7 /** Дали коментарът трябва да бъде изтрит "на живо" за потребителите, които гледат екземпляри на коментарния widget със същия urlId. NOTE: Удва разхода на кредити от 1 на 2. **/

8 isLive?: 'true' | 'false'

9}

10

Структура на отговора за DELETE на коментар

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' | 'locked'

7 /** Включено при неуспех. **/

8 reason?: string

9}

10

Тази API крайна точка предоставя възможност за докладване на коментар за конкретен потребител.

Забележки:

• Това извикване винаги трябва да се прави в контекста на потребител. Потребителят може да бъде FastComments.com потребител, SSO потребител или Tenant потребител.
• Ако е зададен праг за докладване-скриване, коментарът ще бъде автоматично скрит на живо след като бъде докладван определен брой пъти.
• След като бъде автоматично неодобрен (скрит) - коментарът може да бъде повторно одобрен само от администратор или модератор. Премахването на докладването няма да одобри отново коментара.

Пример за докладване на коментар с 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 /** Included on failure. **/

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 /** Included on failure. **/

8 reason?: string

9 /** Was the comment un-approved (hidden) due to being flagged too many times? **/

10 wasUnapproved?: boolean;

11}

12

Тази API крайна точка предоставя възможност за премахване на докладването на коментар за конкретен потребител.

Забележки:

• Това извикване винаги трябва да се прави в контекста на потребител. Потребителят може да бъде FastComments.com потребител, SSO потребител или Tenant потребител.
• След като коментарът е автоматично неодобрен (скрит) - коментарът може да бъде повторно одобрен само от администратор или модератор. Премахването на докладването няма да одобри отново коментара.

Пример за премахване на докладване на коментар с 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 /** Included on failure. **/

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 /** Included on failure. **/

8 reason?: string

9}

10

Тази API крайна точка предоставя възможност за блокиране на потребител, написал даден коментар. Поддържа блокиране от коментари, написани от FastComments.com потребители, SSO потребители и Tenant потребители.

Поддържа параметър commentIdsToCheck в тялото, за да провери дали други потенциално видими коментари на клиента трябва да бъдат блокирани/отблокирани след извършване на това действие.

Забележки:

• Това извикване винаги трябва да се прави в контекста на потребител. Потребителят може да бъде FastComments.com потребител, SSO потребител или Tenant потребител.
• userId в заявката е потребителят, който извършва блокирането. Например: Потребител A иска да блокира Потребител B. Подайте userId=Потребител A и id на коментара, който Потребител B е написал.
• Напълно анонимни коментари (без потребителски 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 /** Included on failure. **/

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 /** Included on failure. **/

8 reason?: string

9 /** If commentIdsToCheck is defined, entries in this map with true are also blocked. **/

10 commentStatuses?: Record<string, boolean>;

11}

12

Тази API крайна точка предоставя възможност за отблокиране на потребител, написал даден коментар. Поддържа отблокиране от коментари, написани от FastComments.com потребители, SSO потребители и Tenant потребители.

Поддържа параметър commentIdsToCheck в тялото, за да провери дали други потенциално видими коментари на клиента трябва да бъдат блокирани/отблокирани след извършване на това действие.

Забележки:

• Това извикване винаги трябва да се прави в контекста на потребител. Потребителят може да бъде FastComments.com потребител, SSO потребител или Tenant потребител.
• userId в заявката е потребителят, който извършва отблокирането. Например: Потребител A иска да отблокира Потребител B. Подайте userId=Потребител A и id на коментара, който Потребител B е написал.
• Напълно анонимни коментари (без потребителски 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 /** Included on failure. **/

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 /** Included on failure. **/

8 reason?: string

9 /** If commentIdsToCheck is defined, entries in this map with true are still blocked. If false, you might want to un-hide the comments from the user so they don't have to refresh. **/

10 commentStatuses?: Record<string, boolean>;

11}

12

Индивидуални EmailTemplates могат да бъдат извлечени по съответния им id (НЕ emailTemplateId).

Пример за EmailTemplate по ID с cURL

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/email-templates/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

4

Структура на заявката за EmailTemplate по ID

Copy

1

2interface EmailTemplatesByIdRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура на отговора за EmailTemplate по ID

Copy

1

2interface EmailTemplateResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

5 code?: 'internal' | 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found'

6 /** Included on failure. **/

7 reason?: string

8 emailTemplate?: EmailTemplate | null

9}

10

Този 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 /** The page to fetch, starting with 0. **/

6 page: number

7}

8

Структура на отговора за EmailTemplate

Copy

1

2interface EmailTemplatesResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'

6 /** Included on failure. **/

7 reason?: string

8 emailTemplates: EmailTemplate[]

9}

10

Тази API крайна точка предоставя възможност за актуализиране на имейл шаблон, като посочите само id и атрибутите за актуализиране.

Имайте предвид, че всички същите валидации за създаване на шаблон се прилагат, например:

• Шаблонът трябва да се визуализира. Това се проверява при всяка актуализация.
• Не можете да имате дублирани шаблони за същия домейн (в противен случай един ще бъде мълчаливо игнориран).

Пример за PATCH на EmailTemplate с 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

Структура на заявката за PATCH на EmailTemplate

Copy

1

2interface EmailTemplatePatchQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура на отговора за PATCH на EmailTemplate

Copy

1

2

3interface EmailTemplatePatchResponse {

4 status: 'success' | 'failed'

5 /** Included on failure. **/

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 /** Included on failure. **/

8 reason?: string

9 /** The updated email template. **/

10 emailTemplate?: EmailTemplate

11}

12

Тази API крайна точка предоставя възможност за създаване на имейл шаблони.

Забележки:

• Не можете да имате множество шаблони с един и същ emailTemplateId с един и същ домейн.
• Но можете да имате универсален шаблон (domain = *) и специфичен за домейн шаблон за същия emailTemplateId.
• Посочването на domain е уместно само ако имате различни домейни или искате да използвате специфични шаблони за тестване (domain зададен на localhost и т.н.).
• Ако посочите domain, той трябва да съвпада с DomainConfig. При грешка се предоставя списък с валидни домейни.
• Синтаксисът на шаблона е EJS и се визуализира с таймаут от 500ms. P99 за визуализация е <5ms, така че ако достигнете 500ms, нещо не е наред.
• Вашият шаблон трябва да се визуализира с вашите дадени testData, за да се запази. Грешките при визуализация се агрегират и докладват в таблото (скоро налично чрез API).

Минималните данни, необходими за добавяне на шаблон, са следните:

Пример за минимален POST на EmailTemplate с 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:

Пример за POST на EmailTemplate с 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

Структура на заявката за POST на EmailTemplate

Copy

1

2interface EmailTemplatePostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура на отговора за POST на EmailTemplate

Copy

1

2

3interface EmailTemplatePostResponse {

4 status: 'success' | 'failed'

5 /** Included on failure. **/

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 /** Included on failure. **/

8 reason?: string

9 /** The created template. **/

10 emailTemplate?: EmailTemplate

11}

12

Тази API крайна точка предоставя възможност за предварителен преглед на имейл шаблони.

Пример за минимален POST за предварителен преглед на EmailTemplate с 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

Структура на заявката за POST на EmailTemplate

Copy

1

2interface EmailTemplatePostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура на отговора за POST на EmailTemplate

Copy

1

2

3interface EmailTemplatePostResponse {

4 status: 'success' | 'failed'

5 /** Included on failure. **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'unexpected-param' | 'does-not-render';

7 /** Included on failure. **/

8 reason?: string

9 /** The rendered HTML on success. **/

10 html?: string

11}

12

Този маршрут предоставя премахването на единичен EmailTemplate по id.

Пример за премахване на EmailTemplate с cURL

Copy

1

2curl --request DELETE \

3 --url 'https://fastcomments.com/api/v1/email-templates/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

4

Структура на заявката за премахване на EmailTemplate

Copy

1

2interface EmailTemplateRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура на отговора за премахване на EmailTemplate

Copy

1

2interface EmailTemplateDeleteResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized'

6 /** Included on failure. **/

7 reason?: string

8}

9

Извлича публикации в емисия, най-новите първи. Пагинацията е базирана на курсор: предайте _id на последната получена публикация като afterId, за да получите следващата страница.

Стои един кредит за всеки десет върнати публикации, с минимум един кредит.

FeedPost cURL пример

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/feed-posts?tenantId=demo&limit=10&API_KEY=DEMO_API_SECRET'

4

FeedPost структура на заявка

Copy

1

2interface FeedPostsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Return posts after this post id. Omit for the first page. **/

6 afterId?: string

7 /** Defaults to 10. Maximum 1000. **/

8 limit?: number

9 /** Only return posts with these tags. Repeat the parameter for more than one tag. **/

10 tags?: string[]

11}

12

FeedPost структура на отговор

Copy

1

2interface FeedPostsResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'limit-invalid' | 'internal'

6 /** Included on failure. **/

7 reason?: string

8 feedPosts: FeedPost[]

9}

10

Този маршрут създава един FeedPost. Всеки пост има автор, затова fromUserId е задължително и трябва да бъде идентификаторът на съществуващ FastComments или SSO потребител в акаунта.

FeedPost Създаване cURL Пример

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/feed-posts?tenantId=demo&isLive=true&API_KEY=DEMO_API_SECRET' \

4 --header 'Content-Type: application/json' \

5 --data '{

6 "fromUserId": "some-user-id",

7 "title": "Release 2.0 is out",

8 "contentHTML": "<p>Read the notes and tell us what you think.</p>",

9 "tags": ["releases"],

10 "links": [

11 {

12 "url": "https://example.com/releases/2.0",

13 "title": "Release notes",

14 "description": "Everything that changed in 2.0."

15 }

16 ]

17}'

18

FeedPost Създаване Структура на заявка

Copy

1

2interface FeedPostPostQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Изпраща поста към емисии, които са отворени в браузъра в момента. По подразбиране е false. **/

6 isLive?: boolean

7 /** Пуска поста през спам двигателя преди запазване. По подразбиране е false. **/

8 doSpamCheck?: boolean

9 /** Пропуска проверката за повторно съдържание, която се изпълнява като част от doSpamCheck. По подразбиране е false. **/

10 skipDupCheck?: boolean

11 /** До 256 знака. Отразява се към живи слушатели, за да може клиентът да игнорира собственото си излъчване. **/

12 broadcastId?: string

13}

14

15interface FeedPostPostBody {

16 /** Задължително. Идентификатор на FastComments или SSO потребител. **/

17 fromUserId: string

18 title?: string

19 /** HTML. По време на запазване се почистват. **/

20 contentHTML?: string

21 /** Презаписва показваното име, взето от потребителя. **/

22 fromUserDisplayName?: string

23 tags?: string[]

24 media?: FeedPostMediaItem[]

25 links?: FeedPostLink[]

26 meta?: Record<string, string>

27}

28

FeedPost Създаване Структура на отговор

Copy

1

2interface FeedPostPostResponse {

3 status: 'success' | 'failed'

4 /** Включено при неуспех. **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-from-user-id' | 'invalid-user' | 'broadcast-id-too-long' | 'spam-blocked' | 'user-rate-limited' | 'internal'

6 /** Включено при неуспех. **/

7 reason?: string

8 feedPost?: FeedPost; // Връщаме целия създаден пост при успех.

9}

10

Този маршрут актуализира един FeedPost. Изпратете само полетата, които искате да промените.

Пример за cURL за актуализиране на FeedPost

Copy

1

2curl --request PATCH \

3 --url 'https://fastcomments.com/api/v1/feed-posts/some-post-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \

4 --header 'Content-Type: application/json' \

5 --data '{

6 "title": "Release 2.0.1 is out",

7 "tags": ["releases", "hotfix"]

8}'

9