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-сервер и другие сторонние интеграции подключаются к сервису.

Токены выдаются через authorization code flow с PKCE. Client credentials и implicit grant не поддерживаются.

Discovery

Расположение эндпоинтов, поддерживаемые grant-типы и методы аутентификации публикуются по стандартному metadata 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 в качестве issuer с теми же путями.

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

Клиенту необходимы client_id и зарегистрированный redirect_uri, прежде чем он сможет начать flow. Есть два способа их получить:

• Dynamic Client Registration. POST /oauth/register с JSON-телом согласно RFC 7591 (redirect_uris, client_name, client_uri, logo_uri, token_endpoint_auth_method). В ответе возвращаются client_id и, для конфиденциальных клиентов, client_secret. Регистрация не требует аутентификации и ограничена по частоте запросов на IP.
• Client ID Metadata Document. Клиент использует https URL, которым он владеет, в качестве своего client_id. FastComments загружает этот URL и читает из него те же поля метаданных. Вызов регистрации не требуется.

Партнёрские приложения, перечисленные в панели управления FastComments, такие как Zapier, регистрируются FastComments напрямую. Свяжитесь с поддержкой, если вы создаёте листинг для маркетплейса и вам нужен first-party клиент.

Scopes

Scopes

Copy

1

2read GET and HEAD requests

3write every other method

4

Запрос без указания scope получает оба. Пользователь видит запрошенные scopes на странице согласия. Запрос scope, отличного от этих двух, завершается ошибкой invalid_scope.

Шаг 1 - Запрос авторизации

Направьте браузер пользователя на эндпоинт authorize. 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 /** Must exactly match one of the client's registered redirect URIs. **/

6 redirect_uri: string

7 /** Space separated. Omit to request both scopes. **/

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

9 /** Returned unchanged on the redirect. Use it to bind the callback to the session that started the flow. **/

10 state?: string

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

12 code_challenge: string

13 code_challenge_method: 'S256'

14 /** Optional RFC 8707 resource indicator. If sent, the same value must be sent to the token endpoint. **/

15 resource?: string

16}

17

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

Код авторизации действителен 10 минут и может быть обменян один раз. Повторный обмен того же кода отзывает все токены, выданные при первом обмене.

Шаг 2 - Запрос токена

Обменяйте код на токены. Тело запроса передаётся в формате form encoded. Конфиденциальные клиенты аутентифицируются через 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 /** Confidential clients only. May be sent as HTTP Basic auth instead. **/

6 client_secret?: string

7 code: string

8 code_verifier: string

9 /** Must match the authorization request when sent. **/

10 redirect_uri?: string

11 resource?: string

12}

13

Структура ответа с токеном

Copy

1

2interface OAuthTokenResponse {

3 /** Prefixed fcat_. Valid for one hour. **/

4 access_token: string

5 token_type: 'bearer'

6 /** Seconds until the access token expires. 3600. **/

7 expires_in: number

8 /** Prefixed fcrt_. Valid for 30 days from issue. **/

9 refresh_token: string

10 /** Space separated scopes granted. **/

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

Отправляйте access token как bearer token. Тенант подразумевается токеном, поэтому tenantId необязателен. Если он указан, он должен совпадать с токеном, иначе запрос завершится ошибкой.

Пример cURL с Bearer токеном

Copy

1

2curl --request GET \

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

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

5

GET /api/v1/me возвращает тенант, авторизующего пользователя и выданные scopes, что делает его подходящим вызовом для проверки соединения. Запрос с истёкшим или отозванным токеном получает HTTP 401. Запрос, метод которого требует scope, которого нет у токена, получает 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 /** Optional. Narrows to a subset of the scopes originally granted. **/

8 scope?: string

9 resource?: string

10}

11

Ответ имеет ту же структуру, что и при обмене кода. Refresh tokens ротируются: каждое обновление возвращает новый refresh_token и отзывает старый после 30-секундного льготного окна для параллельных запросов. Предъявление refresh token, ротированного более 30 секунд назад, считается replay-атакой и отзывает весь grant. Партнёрские приложения, зарегистрированные FastComments, освобождены от ротации и получают тот же refresh token со сроком действия, продлённым ещё на 30 дней.

При обновлении также повторно проверяется, что авторизующий пользователь по-прежнему обладает правом API Admin на аккаунте. Если нет, grant отзывается, и ответом будет 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

Отзыв refresh token отзывает все access token, выданные из того же grant. Отзыв access token отзывает только этот токен. Эндпоинт возвращает HTTP 200 с пустым JSON-объектом независимо от того, был ли найден токен, согласно RFC 7009.

Пользователи также могут отозвать подключение через Connected Apps в панели управления FastComments. Все токены этого приложения перестают работать немедленно.

Этот API агрегирует документы, группируя их (если задан groupBy) и применяя несколько операций. Поддерживаются различные операции (например, sum, countDistinct, avg и т.д.).

Стоимость является переменной. За каждые 500 просканированных объектов взимается 1 кредит API.

По умолчанию максимальный объем памяти, разрешенный для одного вызова API, составляет 64МБ, и по умолчанию у вас может выполняться только одна агрегация одновременно. Если вы отправите несколько агрегаций одновременно, они будут поставлены в очередь и выполнятся в порядке отправки. Ожидающие агрегации будут ждать максимум 60 секунд, после чего запрос завершится по таймауту. Отдельные агрегации могут выполняться до 5 минут.

Если у вас есть управляемые tenants, вы можете агрегировать все ресурсы дочерних tenants в одном вызове, передав параметр запроса 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

Структуры

Структура запроса Aggregate

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

Структура ответа Aggregate

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 для поиска подстроки в метке без учёта регистра, когда известны имя или email человека, но не его id.

При удалении сохраняется метка на момент события, поэтому удалённый пользователь или модератор могут быть идентифицированы даже после удаления исходной записи.

Управляемые арендаторы

Если ваш арендатор управляет другими арендаторами, установите 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 /** Only jobs of this type, for example migrate-pages. **/

6 type?: string

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

8 /** How many jobs to skip, for paging. A non-negative integer. **/

9 skip?: number

10}

11

Структура ответа списка BatchJob

Copy

1

2interface BatchJobsResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

6 /** Included on failure. **/

7 reason?: string

8 /** Newest first, at most 100. **/

9 batchJobs?: BatchJob[]

10}

11

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

Задание считается завершённым, когда его status равен success или failed. Каждый вызов стоит 1 кредит, поэтому опрашивайте каждые несколько секунд, а не постоянно.

Пример cURL для BatchJob по ID

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. Самый быстрый: Предвычисленная пагинация (Precalculated Pagination):
   1. Так работает FastComments, когда вы используете наши готовые виджеты и клиенты.
   2. Нажатие «далее» просто увеличивает номер страницы.
   3. Это можно представить как получение данных из хранилища «ключ-значение».
   4. В этом случае просто задайте параметр page, начиная с 0, и направление сортировки как direction.
   5. Размеры страниц можно настраивать с помощью правил кастомизации.
2. Самый гибкий: Гибкая пагинация (Flexible Pagination):
   1. В этом случае вы можете задать собственные параметры limit и skip. Не передавайте page.
   2. Направление сортировки direction также поддерживается.
   3. limit — это общее количество возвращаемых записей после применения skip.
      • Пример: задайте skip = 200, limit = 100 при page size = 100 и page = 2.
   4. Дочерние комментарии также учитываются в пагинации. Обойти это можно с помощью опции asTree.
      • Дочерние комментарии можно пагинировать через limitChildren и skipChildren.
      • Глубину возвращаемых веток можно ограничить через maxTreeDepth.

Ветки (Threads)

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. Это можно представить как Flexible Pagination as a Tree.
   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

Однако в вашем интерфейсе может потребоваться знать, показывать ли кнопку «показать ответы» на каждом комментарии. При получении комментариев в виде дерева к комментариям, где это применимо, добавляется свойство 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.

Пример cURL-запроса для получения комментария по id

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

Этот API-эндпойнт предоставляет возможность создавать комментарии.

Типичные случаи использования: кастомные интерфейсы, интеграции или импорты.

Примечания:

• Этот API может обновлять виджет комментариев "в реальном времени", если нужно (это увеличивает creditsCost с 1 до 2).
• Этот API автоматически создаст объекты пользователей в нашей системе, если указан адрес электронной почты.
• Попытка сохранить два комментария с разными адресами электронной почты, но с одинаковым именем пользователя приведёт к ошибке для второго комментария.
• Если вы указываете parentId, и дочерний комментарий имеет notificationSentForParent as false, мы отправим уведомления для родительского комментария. Это делается каждый час (мы группируем уведомления вместе, чтобы уменьшить число отправляемых писем).
• Если вы хотите отправлять приветственные письма при создании пользователей или письма для подтверждения комментариев, установите sendEmails в true в параметрах запроса.
• Комментарии, созданные через этот API, будут отображаться на страницах Analytics и Moderation в административном приложении.
• "bad words" по-прежнему маскируются в именах комментаторов и тексте комментария, если настройка включена.
• Комментарии, созданные через этот API, по-прежнему можно проверять на спам при необходимости.
• Настройки, такие как максимальная длина комментария, если они настроены через страницу администрирования Customization Rule, будут применяться и здесь.

Минимальные данные, необходимые для отправки и отображения в виджете комментариев, выглядят следующим образом:

Минимальный пример 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

Этот API-эндпоинт предоставляет возможность обновить один комментарий.

Notes:

• Этот API может обновлять виджет комментариев "вживую" при желании (this increases base creditsCost from 1 to 2).
  • Это может сделать миграцию комментариев между страницами "вживую" (changing urlId).
  • Миграции стоят дополнительные 2 кредита, так как страницы предрассчитываются и это ресурсоёмко для CPU.
• В отличие от create API, этот API НЕ будет автоматически создавать объекты пользователей в нашей системе, если указан адрес электронной почты.
• Комментарии, обновлённые через этот API, по-прежнему можно проверять на спам при желании.
• Конфигурации, такие как максимальная длина комментария, если настроены через страницу администрирования Customization Rule, будут применяться здесь.
• Чтобы позволить пользователям обновлять текст своего комментария, вы можете просто указать comment в теле запроса. Мы сгенерируем результирующий commentHTML.
  • Если вы зададите и comment, и commentHTML, мы не будем автоматически генерировать HTML.
  • Если пользователь добавит упоминания или хэштеги в новом тексте, они всё равно будут обрабатываться так же, как в POST API.
• При обновлении commenterEmail в комментарии лучше также указать userId. В противном случае вы должны убедиться, что пользователь с этим адресом электронной почты принадлежит вашему тенанту, иначе запрос завершится ошибкой.
• Если целевой комментарий заблокирован (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. NOTE: Doubles credit cost from 1 to 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 может обновлять виджет комментариев "вживую", если необходимо (это увеличивает 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 /** Нужно ли удалять комментарий "вживую" для пользователей, просматривающих экземпляры виджета комментариев с тем же urlId. ПРИМЕЧАНИЕ: Удваивает стоимость в кредитах с 1 до 2. **/

8 isLive?: 'true' | 'false'

9}

10

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

Copy

1

2

3interface CommentDeleteResponse {

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

7 /** Включено при ошибке. **/

8 reason?: string

9}

10

Этот API-эндпоинт предоставляет возможность пометить комментарий для конкретного пользователя.

Примечания:

• Этот вызов всегда должен выполняться в контексте пользователя. Пользователем может быть пользователь FastComments.com, SSO-пользователь или пользователь арендатора.
• Если установлен порог для скрытия по флагам, комментарий будет автоматически скрыт в реальном времени после того, как его пометят заданное количество раз.
• После того как он автоматически снят с одобрения (скрыт) - комментарий может быть повторно одобрен только администратором или модератором. Снятие флага не восстановит одобрение комментария.

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

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/flag?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \

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

5

Для анонимной пометки мы должны указать anonUserId. Это может быть идентификатор, представляющий анонимную сессию, или случайный UUID. Это позволяет поддерживать пометку и снятие пометки с комментариев, даже если пользователь не вошёл в систему. Таким образом комментарий может быть помечен как flagged при получении комментариев с тем же 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

Этот API-эндпоинт позволяет снять флаг с комментария для конкретного пользователя.

Примечания:

• Этот вызов всегда должен выполняться в контексте пользователя. Пользователем может быть FastComments.com User, SSO User, или Tenant User.
• После того как комментарий автоматически помечается как неодобренный (скрыт) — комментарий может быть повторно одобрен только администратором или модератором. Снятие флага не приведёт к повторному одобрению комментария.

Пример cURL запроса для снятия флага с комментария

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-flag?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \

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

5

Для анонимной пометки необходимо указать anonUserId. Это может быть идентификатор, представляющий анонимную сессию, или случайный 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

Этот API-эндпоинт предоставляет возможность заблокировать пользователя, который написал указанный комментарий. Поддерживается блокировка комментариев, написанных пользователями FastComments.com, SSO-пользователями и Tenant-пользователями.

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

Примечания:

• Этот вызов всегда должен выполняться в контексте пользователя. Пользователь может быть FastComments.com User, SSO User или Tenant User.
• userId в запросе — это пользователь, который выполняет блокировку. Например: User A хочет заблокировать User B. Передайте userId=User A и идентификатор комментария, который написал User B.
• Полностью анонимные комментарии (без user id и без email) не могут быть заблокированы, и будет возвращена ошибка.

Пример 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. Это может быть идентификатор, представляющий анонимную сессию, или случайный 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

Этот конечный пункт API предоставляет возможность разблокировать пользователя, который написал данный комментарий. Поддерживается разблокировка комментариев, написанных пользователями FastComments.com, SSO-пользователями и пользователями арендатора.

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

Примечания:

• Вызов всегда должен выполняться в контексте пользователя. Пользователь может быть пользователем FastComments.com, SSO-пользователем или пользователем арендатора.
• Поле userId в запросе — это пользователь, который выполняет разблокировку. Например: User A хочет разблокировать User B. Передайте userId=User A и идентификатор комментария, который написал User B.
• Полностью анонимные комментарии (без user id, без email) не могут быть заблокированы — будет возвращена ошибка.

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

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-block?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \

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

5

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

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-block?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \

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

5

Структура запроса на разблокировку комментария

Copy

1

2interface CommentUnBlockQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7 commentIdsToCheck?: string[]

8}

9

Структура ответа на разблокировку комментария

Copy

1

2

3interface CommentUnBlockResponse {

4 status: 'success' | 'failed'

5 /** Включается при ошибке. **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id' | 'comment-cannot-be-blocked'

7 /** Включается при ошибке. **/

8 reason?: string

9 /** Если определён commentIdsToCheck, записи в этой карте со значением true остаются заблокированными. Если false, вы, возможно, захотите снова показать эти комментарии пользователю, чтобы ему не пришлось обновлять страницу. **/

10 commentStatuses?: Record<string, boolean>;

11}

12

Отдельные EmailTemplates можно получить по соответствующему id (НЕ emailTemplateId).

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

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 /** Включается при ошибке. **/

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

Этот API использует пагинацию, задаваемую параметром запроса page. EmailTemplates возвращаются страницами по 100, отсортированными по createdAt, а затем по id.

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

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

Этот API-эндпоинт позволяет обновлять шаблон письма, указывая только id и атрибуты, которые нужно изменить.

Обратите внимание, что те же проверки, что и при создании шаблона, также применяются, например:

• Шаблон должен корректно рендериться. Это проверяется при каждом обновлении.
• Нельзя иметь дублирующиеся шаблоны для одного и того же домена (в противном случае один из них будет молча игнорироваться).

Пример cURL-запроса для EmailTemplate PATCH

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

Этот API-эндпоинт предоставляет возможность создавать шаблоны электронных писем.

Примечания:

• У вас не может быть нескольких шаблонов с одинаковым emailTemplateId в одном и том же домене.
• Но вы можете иметь шаблон-джокер (domain = *) и шаблон, специфичный для домена, для того же emailTemplateId.
• Указание domain имеет значение только если у вас несколько доменов или вы хотите использовать специфичные шаблоны для тестирования (например, domain = localhost).
• Если вы указываете domain, он должен соответствовать DomainConfig. В случае ошибки предоставляется список допустимых доменов.
• Синтаксис шаблонов — EJS, и рендеринг выполняется с таймаутом 500 мс. P99 времени рендеринга <5ms, поэтому если вы достигаете 500ms — что-то не так.
• Ваш шаблон должен успешно рендериться с предоставленными testData для сохранения. Ошибки рендеринга агрегируются и отображаются на панели (вскоре будет доступно через API).

Минимальные данные, необходимые для добавления шаблона, следующие:

Минимальный пример cURL POST для EmailTemplate

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:

Пример cURL POST для EmailTemplate

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 /** Включается при ошибке. **/

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

Этот API-эндпойнт предоставляет возможность предварительного просмотра шаблонов электронной почты.

Минимальный пример cURL запроса POST для предварительного просмотра EmailTemplate

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 /** Указывается в случае ошибки. **/

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

Этот маршрут позволяет удалить один EmailTemplate по идентификатору.

Пример cURL-запроса удаления EmailTemplate

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

Получает посты в ленте, начиная с самых новых. Пагинация основана на курсоре: передайте _id последнего полученного поста в параметр afterId, чтобы получить следующую страницу.

Стоимость — один кредит за каждые десять возвращённых постов, минимум один кредит.

Пример cURL для FeedPost

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 /** Возвращать посты после этого идентификатора поста. Пропустите для первой страницы. **/

6 afterId?: string

7 /** По умолчанию 10. Максимум 1000. **/

8 limit?: number

9 /** Возвращать только посты с этими тегами. Повторите параметр для более чем одного тега. **/

10 tags?: string[]

11}

12

Структура ответа FeedPost

Copy

1

2interface FeedPostsResponse {

3 status: 'success' | 'failed'

4 /** Включается при ошибке. **/

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

6 /** Включается при ошибке. **/

7 reason?: string

8 feedPosts: FeedPost[]

9}

10

Этот маршрут создаёт один FeedPost. Каждый пост имеет автора, поэтому fromUserId обязателен и должен быть идентификатором существующего пользователя FastComments или SSO в аккаунте.

Пример cURL для создания FeedPost

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