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

Следует отметить, что получение данных из API учитывается как использование на вашем аккаунте.

Каждый ресурс в своём разделе указывает, что именно считается использованием.

Некоторые ресурсы обходятся дороже, чем другие. Каждая конечная точка имеет установленную стоимость в кредитах за вызов API. Для некоторых конечных точек количество кредитов варьируется в зависимости от опций и размеров ответа.

Использование API можно проверить на странице Аналитика выставления счетов — данные обновляются каждые несколько минут.

Примечание!

Мы рекомендуем сначала прочитать документацию Pages, чтобы уменьшить путаницу при определении того, какие значения передавать для urlId в Comment API.

Этот 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, before и after. Журналы аудита возвращаются страницами по 1000, отсортированные по when и id.

Получение каждых 1000 записей журнала стоит 10 кредитов.

По умолчанию вы получите список с самыми новыми элементами первыми. Таким образом, вы можете опрашивать, начиная с skip=0, постранично, пока не найдете последнюю запись, которую вы обработали.

В качестве альтернативы, вы можете сортировать от старых к новым и постранично получать данные, пока записи не закончатся.

Сортировка выполняется установкой order в ASC или DESC. Значение по умолчанию — ASC.

Фильтрация по дате возможна с помощью before и after в виде меток времени с миллисекундами. before и after НЕ включают указанные значения.

Пример 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 CommentsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 order?: 'ASC' | 'DESC'

6 skip?: number

7 before?: number

8 after?: number

9}

10

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

Copy

1

2interface CommentsResponse {

3 status: 'success' | 'failed'

4 /** Указывается при ошибке. **/

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

6 /** Указывается при ошибке. **/

7 reason?: string

8 /** Журналы аудита! **/

9 auditLogs: AuditLog[]

10}

11

Этот API используется для получения комментариев для отображения пользователю. Например, он автоматически фильтрует неодобренные или спам-комментарии.

Пагинация

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

1. Самый быстрый: Precalculated Pagination:
   1. Так работает FastComments, когда вы используете наши преднастроенные виджеты и клиенты.
   2. Нажатие "next" просто увеличивает номер страницы.
   3. Можно считать, что данные извлекаются из key-value хранилища.
   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.

Треды

1. При использовании Precalculated Pagination комментарии группируются по странице, и комментарии в тредах влияют на общую страницу.
   1. Таким образом, треды могут быть определены на клиенте на основе parentId.
   2. Например, на странице с одним комментарием верхнего уровня и 29 ответами, при установке page=0 в API — вы получите только корневой комментарий и 29 детей.
   3. Примерное изображение, иллюстрирующее несколько страниц.
2. При использовании Flexible Pagination вы можете задать параметр parentId.
   1. Установите его в null, чтобы получить только комментарии верхнего уровня.
   2. Затем, чтобы просмотреть треды, вызовите API снова и передайте parentId.
   3. Распространённое решение — сделать вызов API для комментариев верхнего уровня, а затем параллельно сделать вызовы API, чтобы получить комментарии для детей каждого комментария.
3. NEW As of Feb 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

Однако в вашем 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.

Пример 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-эндпоинт предоставляет возможность обновления одного комментария.

Примечания:

• Этот API может обновлять виджет комментариев "в реальном времени", если нужно (это увеличит базовую creditsCost с 1 до 2).
  • Это позволяет делать миграции комментариев между страницами "в реальном времени" (изменяя urlId).
  • Миграции стоят дополнительно 2 кредита, так как страницы предварительно вычисляются, и это интенсивно по использованию CPU.
• В отличие от API создания, этот API НЕ будет автоматически создавать объекты пользователя в нашей системе, если указан email.
• Комментарии, обновлённые через этот API, по-прежнему могут проверяться на спам при необходимости.
• Конфигурации, такие как максимальная длина комментария, если настроены через страницу администратора Customization Rule, будут применяться здесь.
• Чтобы позволить пользователям обновлять текст комментария, можно просто указать comment в теле запроса. Мы сгенерируем результирующий commentHTML.
  • Если вы укажете и comment, и commentHTML, мы не будем автоматически генерировать HTML.
  • Если пользователь добавит упоминания или хэштеги в новом тексте, они по-прежнему будут обрабатываться так же, как в POST API.
• При обновлении commenterEmail для комментария лучше также указать userId. В противном случае вы должны убедиться, что пользователь с этим email принадлежит вашему тенанту, иначе запрос завершится ошибкой.

Минимальный пример PATCH cURL для комментария

Copy

1

2curl --request PATCH \

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

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

5 --data '{

6 "comment": "some-new-comment-text"

7}'

8

Структура PATCH-запроса комментария

Copy

1

2interface CommentPatchQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Пользователь, выполняющий обновление. При желании можно использовать для проверки, что он может редактировать комментарий. **/

6 contextUserId?: string

7 /** Проверять ли, похож ли новый комментарий на спам? **/

8 doSpamCheck?: 'true' | 'false'

9 /** Должен ли комментарий появляться "в реальном времени" для пользователей, просматривающих экземпляры виджета комментариев с тем же urlId. ВНИМАНИЕ: удваивает стоимость в кредитах с 1 до 2. **/

10 isLive?: 'true' | 'false'

11}

12

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

Copy

1

2

3interface CommentPatchResponse {

4 status: 'success' | 'failed'

5 /** Включается в случае неудачи. **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-comment' | 'comment-too-big' | 'hash-tags-readonly' | 'mentions-readonly' | 'invalid-user' | 'unauthorized' | 'invalid-date' | 'invalid-name' | 'invalid-name-is-email' | 'banned' | 'invalid-email' | 'invalid-input' | 'missing-id' | 'not-found'

7 /** Включается в случае неудачи. **/

8 reason?: string

9}

10

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

Примечания:

• Этот API может обновлять виджет комментариев "в реальном времени", если требуется (это увеличивает creditsCost с 1 до 2).
• Этот API удалит все дочерние комментарии.

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

Copy

1

2curl --request DELETE \

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

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

5

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

Copy

1

2interface CommentDeleteQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Пользователь, выполняющий обновление. При необходимости можно использовать для проверки, может ли он удалить комментарий. **/

6 contextUserId?: string

7 /** Будет ли комментарий удалён "вживую" для пользователей, просматривающих экземпляры виджета комментариев с тем же urlId. ПРИМЕЧАНИЕ: Удваивает стоимость в кредитах с 1 до 2. **/

8 isLive?: 'true' | 'false'

9}

10

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

Copy

1

2

3interface CommentDeleteResponse {

4 status: 'success' | 'failed'

5 /** Указывается при неудаче. **/

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

7 /** Указывается при неудаче. **/

8 reason?: string

9}

10

Этот 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

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

Пример запроса cURL для HashTag

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/hash-tags?tenantId=demo&page=0&API_KEY=DEMO_API_SECRET'

4

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

Copy

1

2interface HashTagsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Страница для получения, начинается с 0. **/

6 page: number

7}

8

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

Copy

1

2interface HashTagsResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

6 /** Included on failure. **/

7 reason?: string

8 /** The hashtags! **/

9 hashTags: HashTag[]

10}

11

Этот маршрут позволяет обновить один HashTag.

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

Copy

1

2curl --request PATCH \

3 --url 'https://fastcomments.com/api/v1/hash-tags/%23example_hash_tag?tenantId=demo&API_KEY=DEMO_API_SECRET' \

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

5 --data '{

6 "url": "https://example.com/some-`page`"

7}'

8

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

Copy

1

2interface HashTagPatchQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура ответа при обновлении HashTag

Copy

1

2interface HashTagPatchResponse {

3 status: 'success' | 'failed'

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

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist' | 'url-too-long' | 'invalid-tag' | 'already-exists'

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

7 reason?: string

8 hashTag?: HashTag; // Мы возвращаем полностью обновлённый хэштег при успешном выполнении.

9}

10

Этот маршрут позволяет добавить один HashTag.

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

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/hash-tags?tenantId=demo&API_KEY=DEMO_API_SECRET' \

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

5 --data '{

6 "tag": "#example",

7 "url": "https://example.com/some-page"

8}'

9

Структура запроса для создания HashTag

Copy

1

2interface HashTagPostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура ответа для создания HashTag

Copy

1

2interface HashTagPostResponse {

3 status: 'success' | 'failed'

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

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist' | 'url-too-long' | 'invalid-tag'

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

7 reason?: string

8 hashTag?: HashTag; // В случае успеха возвращаем полностью созданный хэштег.

9}

10

Этот маршрут позволяет добавить до 100 объектов HashTag за один раз.

Пример cURL-запроса для массового создания HashTag

Copy

1

2curl --request PATCH \

3 --url 'https://fastcomments.com/api/v1/hash-tags/bulk?tenantId=demo&API_KEY=DEMO_API_SECRET' \

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

5 --data '{

6 "tags": [

7 {

8 "tag": "#example",

9 "url": "https://example.com/some-page"

10 }

11 ]

12}'

13

Структура запроса для массового создания HashTag

Copy

1

2interface HashTagPostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура ответа при массовом создании HashTag

Copy

1

2interface HashTagBulkPostResponse {

3 status: 'success' | 'failed'

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

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist' | 'url-too-long' | 'invalid-tag'

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

7 reason?: string

8 results?: HashTagPostResponse[]; // Мы возвращаем список объектов HashTagPostResponse для каждого переданного тега.

9}

10

Этот маршрут предоставляет удаление HashTag по указанному тегу.

Обратите внимание, что если автоматическое создание HashTag не отключено, хэштеги могут быть воссозданы пользователем, указавшим хэштег при комментировании.

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

Copy

1

2curl --request DELETE \

3 --url 'https://fastcomments.com/api/v1/hash-tags/%23example_hash_tag?tenantId=demo&API_KEY=DEMO_API_SECRET'

4

Структура запроса на удаление HashTag

Copy

1

2interface HashTagDeleteQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура ответа на удаление HashTag

Copy

1

2interface HashTagDeleteResponse {

3 status: 'success' | 'failed'

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

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist'

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

7 reason?: string

8}

9

Объект Moderator представляет конфигурацию модератора.

Существует три типа модераторов:

1. Администраторы, у которых установлен флаг isCommentModeratorAdmin.
2. Пользователи SSO с флагом isCommentModeratorAdmin.
3. Обычные комментаторы, или пользователи FastComments.com, приглашённые в модераторы.

Структура Moderator используется для представления состояния модерации в случае использования 3.

Если вы хотите пригласить пользователя стать модератором через API, используйте API Moderator, создав Moderator и пригласив его.

Если у пользователя нет аккаунта на FastComments.com, письмо с приглашением поможет ему настроиться. Если у него уже есть аккаунт, ему будет предоставлен доступ модератора к вашему тенанту и поле userId объекта Moderator будет обновлено, чтобы указывать на его пользователя. Вы не будете иметь доступа к их пользователю через API, так как в этом случае он принадлежит им и управляется FastComments.com.

Если вам требуется полный контроль над учётной записью пользователя, мы рекомендуем либо использовать SSO, либо добавить их в качестве Tenant User и затем добавить объект Moderator для отслеживания их статистики.

Структуру Moderator можно использовать как механизм отслеживания статистики для случаев использования 1 и 2. После создания пользователя добавьте объект Moderator с указанным userId, и их статистика будет отслеживаться на странице Comment Moderators Page.

Структура объекта Moderator выглядит следующим образом:

Структура объекта Moderator

Copy

1

2interface Moderator {

3 name: string

4 email: string

5 tenantId: string

6 userId?: string|null

7 acceptedInvite?: boolean

8 markReviewedCount?: number

9 deletedCount?: number

10 markedSpamCount?: number

11 approvedCount?: number

12 editedCount?: number

13 bannedCount?: number

14 createdAt: string

15 moderationGroupIds?: string[]|null

16}

17

Этот маршрут возвращает одного модератора по его id.

Пример cURL-запроса для модератора по ID

Copy

1

2curl --request GET \

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

4

Структура запроса модератора

Copy

1

2interface ModeratorByIdQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура ответа модератора

Copy

1

2interface ModeratorByIdResponse {

3 status: 'success' | 'failed'

4 /** Указывается при ошибке. **/

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

6 /** Указывается при ошибке. **/

7 reason?: string

8 moderator?: Moderator

9}

10

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

Стоимость основана на количестве возвращенных модераторов: 1 credit per 10 возвращенных модераторов.

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

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/moderators?tenantId=demo&skip=0&API_KEY=DEMO_API_SECRET'

4

Структура запроса для Moderator

Copy

1

2interface ModeratorsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Количество модераторов, которые нужно пропустить для пагинации. **/

6 skip?: number

7}

8

Структура ответа для Moderator

Copy

1

2interface ModeratorsResponse {

3 status: 'success' | 'failed'

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

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

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

7 reason?: string

8 moderators?: Moderator[]

9}

10

Этот эндпоинт API позволяет обновить Moderator по id.

Обновление Moderator имеет следующие ограничения:

• Следующие значения не могут быть указаны при обновлении Moderator:
  • acceptedInvite
  • markReviewedCount
  • deletedCount
  • markedSpamCount
  • approvedCount
  • editedCount
  • bannedCount
  • verificationId
  • createdAt
• Если указан userId, такой пользователь должен существовать.
• Если указан userId, он должен принадлежать тому же tenantId, который указан в параметрах запроса.
• Нельзя добавить двух модераторов в одном и том же tenant с одинаковым email.
• Нельзя изменить tenantId, связанный с Moderator.

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

Copy

1

2curl --request PATCH \

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

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

5 --data '{

6 "name": "Some New Name",

7}'

8

Структура запроса Moderator PATCH

Copy

1

2interface ModeratorPatchQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура ответа Moderator PATCH

Copy

1

2

3interface ModeratorPatchResponse {

4 status: 'success' | 'failed'

5 /** Указывается при ошибке. **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'name-required' | 'email-required' | 'unexpected-param' | 'not-found';

7 /** Указывается при ошибке. **/

8 reason?: string

9}

10

Этот маршрут позволяет добавить одного Moderator.

Создание Moderator имеет следующие ограничения:

• Всегда необходимо указывать name и email. userId является необязательным.
• Следующие значения не могут быть указаны при создании Moderator:
  • acceptedInvite
  • markReviewedCount
  • deletedCount
  • markedSpamCount
  • approvedCount
  • editedCount
  • bannedCount
  • verificationId
  • createdAt
• Если указан userId, такой пользователь должен существовать.
• Если указан userId, он должен принадлежать тому же tenantId, который указан в параметрах запроса.
• Нельзя добавить двух модераторов в одном тенанте с одинаковым email.

Мы можем создать Moderator для пользователя, о котором известен только email:

Пример cURL: создание Moderator по электронной почте

Copy

1

2curl --request POST \

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

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

5 --data '{

6 "name": "Some Name",

7 "email": "someone@someone.com"

8}'

9

Или мы можем создать Moderator для пользователя, который принадлежит нашему тенанту, чтобы отслеживать его статистику модерации:

Пример cURL: создание Moderator для пользователя тенанта

Copy

1

2curl --request POST \

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

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

5 --data '{

6 "name": "Some Name",

7 "email": "someone@someone.com",

8 "userId": "some-tenant-user-id"

9}'

10

Структура запроса для создания Moderator

Copy

1

2interface ModeratorPostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура ответа при создании Moderator

Copy

1

2interface ModeratorPostResponse {

3 status: 'success' | 'failed'

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

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'name-required' | 'email-required' | 'unexpected-param' | 'not-found'

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

7 reason?: string

8 moderator?: Moderator; // Мы возвращаем полностью созданного модератора в случае успеха.

9}

10

Этот маршрут предоставляет возможность пригласить одного Moderator.

Существуют следующие ограничения для отправки электронного приглашения Moderator:

• Moderator должен уже существовать.
• fromName не может быть длиннее 100 characters.

Примечания:

• Если пользователь с указанным адресом электронной почты уже существует, ему будет отправлено приглашение модерировать комментарии вашего тенанта.
• Если пользователь с указанным адресом электронной почты не существует, ссылка-приглашение проведет его через процесс создания аккаунта.
• Срок действия приглашения истечет через 30 days.

Мы можем создать Moderator для пользователя, о котором известен только адрес электронной почты:

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

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/moderators/xyz/send-invite?tenantId=demo&API_KEY=DEMO_API_SECRET&fromName=Bob' \

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

5

Это отправит письмо вроде Bob at TenantName is inviting you to be a moderator...

Структура запроса приглашения модератора

Copy

1

2interface ModeratorSendInviteQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Электронное письмо, отправленное пользователю, будет выглядеть как отправленное от этого имени. **/

6 fromName: string

7}

8

Структура ответа на приглашение модератора

Copy

1

2interface ModeratorSendInviteResponse {

3 status: 'success' | 'failed'

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

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

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

7 reason?: string

8}

9

Этот маршрут обеспечивает удаление Moderator по id.

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

Copy

1

2curl --request DELETE \

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

4

Структура запроса на удаление модератора

Copy

1

2interface ModeratorDeleteQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура ответа при удалении модератора

Copy

1

2interface ModeratorDeleteResponse {

3 status: 'success' | 'failed'

4 /** Указывается при ошибке. **/

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

6 /** Указывается при ошибке. **/

7 reason?: string

8}

9

Этот маршрут возвращает один NotificationCount по идентификатору пользователя. При SSO идентификатор пользователя имеет формат <tenant id>:<user id>.

Если нет непрочитанных уведомлений, NotificationCount не будет — вы получите 404.

Это отличается от notifications/count тем, что работает быстрее, но не позволяет фильтровать.

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

Copy

1

2curl --request GET \

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

4# -> {"status":"success","data":{"count":1,"createdAt":"2023-03-06T18:45:01.726Z","expireAt":"2024-03-06T01:25:01.726Z","id":"example"}}

5

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

Copy

1

2interface NotificationCountGetQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

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

Copy

1

2interface NotificationCountGetResponse {

3 status: 'success' | 'failed'

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

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

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

7 reason?: string

8 data?: NotificationCount

9}

10

Этот маршрут удаляет один NotificationCount по идентификатору пользователя. При SSO идентификатор пользователя имеет формат <tenant id>:<user id>.

Это очистит счётчик непрочитанных уведомлений пользователя (красный колокольчик в виджете комментариев исчезнет, и число уведомлений пропадёт).

Пример cURL запроса DELETE NotificationCount

Copy

1

2curl --request DELETE \

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

4# -> {"status":"success"}

5

Структура запроса удаления NotificationCount

Copy

1

2interface NotificationCountDeleteQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура ответа при удалении NotificationCount

Copy

1

2interface NotificationCountDeleteResponse {

3 status: 'success' | 'failed'

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

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

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

7 reason?: string

8}

9