API | FastComments Docs

The FastComments API

FastComments предоставляет API для взаимодействия с множеством ресурсов. Создавайте интеграции с нашей платформой или даже пишите собственных клиентов!

В этой документации вы найдёте все поддерживаемые API ресурсы с описанием типов запросов и ответов.

Для корпоративных клиентов весь доступ к API фиксируется в журнале аудита.

Generated SDKs

FastComments теперь генерирует Спецификация API из нашего кода (это ещё не завершено, но включает многие API).

У нас также есть SDK для популярных языков:

Authentication

Доступ к API осуществляется путём передачи вашего API-ключа либо в заголовке X-API-KEY, либо в параметре запроса API_KEY. Для вызова API вам также понадобится ваш tenantId — его можно получить на той же странице, что и ваш API-ключ.

Security Note

Эти маршруты предназначены для вызова с сервера. НЕ вызывайте их из браузера. В противном случае вы выставите ваш API-ключ — это даст полный доступ к вашей учётной записи любому, кто может просмотреть исходный код страницы!

Authentication Option One - Headers

Header: X-API-KEY
Header: X-TENANT-ID

Authentication Option Two - Query Parameters

Query Param: API_KEY
Query Param: tenantId

Ресурсы API

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

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

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

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

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

Примечание!

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

Агрегирование данных

Resource: Aggregate as GET /api/v1/aggregate Credit Cost: 1

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

Стоимость — переменная. Каждые 500 просканированных объектов стоят 1 API-кредит.

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

Если у вас есть управляемые тенанты, вы можете агрегировать все ресурсы дочерних тенантов в одном вызове, передав query-параметр parentTenantId.

Примеры

Пример: Подсчёт уникальных значений

Пример cURL запроса: подсчёт уникальных значений

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "distinct", "field": "urlId", "alias": "urlId" },
        { "op": "distinct", "field": "commenterEmail", "alias": "commenterEmail" }
    ]
}'

Ответ: подсчёт уникальных значений

Copy

{
    "status": "success",
    "data": [
        {
            "commenterEmail": {
                "distinctCounts": {
                    "someone@somewhere.com": 1,
                    "someone2@somewhere.com": 1
                }
            }
        },
        {
            "urlId": {
                "distinctCounts": {
                    "some-page": 2
                }
            }
        }
    ],
    "stats": { "scanned": 2 }
}

Пример: Подсчёт количества различных значений

Пример cURL запроса: подсчёт количества различных значений

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "countDistinct", "field": "urlId", "alias": "urlId" },
        { "op": "countDistinct", "field": "commenterEmail", "alias": "commenterEmail" }
    ]
}'

Ответ:

Ответ: подсчёт количества различных значений

Copy

{
    "status": "success",
    "data": [
        {
            "commenterEmail": { "distinctCount": 2 },
            "urlId": { "distinctCount": 1 }
        }
    ],
    "stats": { "scanned": 2 }
}

Пример: Суммирование значений нескольких полей

Пример cURL запроса: суммирование значений

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "sum", "field": "votes", "alias": "votes" },
        { "op": "sum", "field": "votesUp", "alias": "votesUp" }
    ]
}'

Ответ:

Ответ: суммирование значений

Copy

{
    "status": "success",
    "data": [
        {
            "votes": { "numericValue": 2 },
            "votesUp": { "numericValue": 2 }
        }
    ],
    "stats": { "scanned": 2 }
}

Пример: Средние значения нескольких полей

Пример cURL запроса: средние значения

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "avg", "field": "votes", "alias": "votes" },
        { "op": "avg", "field": "votesUp", "alias": "votesUp" }
    ]
}'

Ответ:

Ответ: средние значения

Copy

{
    "status": "success",
    "data": [
        {
            "votes": { "numericValue": 1 },
            "votesUp": { "numericValue": 1 }
        }
    ],
    "stats": { "scanned": 2 }
}

Пример: Минимальные/максимальные значения нескольких полей

Пример cURL запроса: минимальные/максимальные значения

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "min", "field": "votes", "alias": "votes" },
        { "op": "min", "field": "votesUp", "alias": "votesUp" },
        { "op": "max", "field": "votes", "alias": "votes" },
        { "op": "max", "field": "votesUp", "alias": "votesUp" }
    ]
}'

Ответ:

Ответ: минимальные/максимальные значения

Copy

{
    "status": "success",
    "data": [
        {
            "votes": { "numericValue": 0 },
            "votesUp": { "numericValue": 0 },
            "votes": { "numericValue": 2 },
            "votesUp": { "numericValue": 2 }
        }
    ],
    "stats": { "scanned": 2 }
}

Пример: Подсчёт уникальных значений нескольких полей

Пример cURL запроса: подсчёт уникальных значений

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "distinct", "field": "urlId", "alias": "urlId" },
        { "op": "distinct", "field": "commenterEmail", "alias": "commenterEmail" }
    ]
}'

Ответ:

Ответ: подсчёт уникальных значений

Copy

{
    "status": "success",
    "data": [
        {
            "commenterEmail": {
                "distinctCounts": {
                    "someone@somewhere.com": 1,
                    "someone2@somewhere.com": 1
                }
            },
            "urlId": {
                "distinctCounts": {
                    "some-page": 2
                }
            }
        }
    ],
    "stats": { "scanned": 2 }
}

Пример: Создание запроса

Пример cURL запроса: создание запроса

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "groupBy": ["commenterName"],
    "query": [
        { "key": "approved", "value": true, "operator": "eq" },
        { "key": "commenterName", "value": "some-username-2", "operator": "eq" }
    ],
    "operations": [
        { "op": "sum", "field": "votes", "alias": "votes" }
    ]
}'

Ответ:

Ответ: создание запроса

Copy

{
    "status": "success",
    "data": [
        {
            "groups": { "commenterName": "some-username-2" },
            "votes": { "numericValue": 2 }
        }
    ],
    "stats": { "scanned": 1 }
}

Пример: Подсчёт комментариев, ожидающих проверки

Пример cURL запроса: подсчёт комментариев, ожидающих проверки

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "query": [
        { "key": "reviewed", "value": true, "operator": "not_eq" }
    ],
    "operations": [
        { "op": "count", "field": "id", "alias": "count" }
    ]
}'

Ответ:

Ответ: подсчёт комментариев, ожидающих проверки

Copy

{
    "status": "success",
    "data": [
        { "count": { "numericValue": 2 } }
    ],
    "stats": { "scanned": 2 }
}

Пример: Разбивка по утверждённым, просмотренным и спам-комментариям

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

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "distinct", "field": "approved", "alias": "approved" },
        { "op": "distinct", "field": "reviewed", "alias": "reviewed" },
        { "op": "distinct", "field": "isSpam", "alias": "isSpam" }
    ]
}'

Ответ:

Ответ: разбивка комментариев

Copy

{
    "status": "success",
    "data": [
        {
            "approved": { "distinctCounts": { "true": 2 } },
            "reviewed": { "distinctCounts": { "false": 2 } },
            "isSpam": { "distinctCounts": { "false": 2 } }
        }
    ],
    "stats": { "scanned": 2 }
}

Структуры

Структура запроса агрегации

Copy

export type AggregationOpType = 'sum' | 'countDistinct' | 'distinct' | 'avg' | 'min' | 'max' | 'count';
/** Операция, которая будет применяться к полю */
export interface AggregationOperation {
    /** Поле, над которым будет выполняться операция */
    field: string;
    /** Тип операции */
    op: AggregationOpType;
    /** Необязательный псевдоним для вывода; если не указан, вычисляется псевдоним по умолчанию */
    alias?: string;
    expandArray?: boolean;
}
export interface QueryPredicate {
    key: string
    value: string | number | boolean
    operator: 'eq' | 'not_eq' | 'greater_than' | 'less_than' | 'contains'
}
export interface AggregationRequest {
    query?: QueryPredicate[];
    resourceName: string;
    groupBy?: string[];
    operations: AggregationOperation[];
    sort?: {
        field: string;
        dir: 'asc' | 'desc';
    };
}
type DistinctAccumulator = Record<string, number>;
type GroupValues = Record<string, string>;
export type AggregationValue = {
    distinctCounts?: DistinctAccumulator
    distinctCount?: number
    numericValue?: number
    stringValue?: string
    groups?: GroupValues
};

Структура ответа агрегации

Copy

export type AggregationItem = Record<string, AggregationValue> & { groups?: GroupValues };
export interface AggregationResponse {
    status: APIStatus,
    data: AggregationItem[];
    stats?: {
        scanned: number;
        timeMS: number;
    };
}

Следующие ресурсы можно агрегировать:

AffiliateEvent
AnonymousVote
BannedUser
BatchJob
BlockedUser
Comment
CommentDeleted
CommentIdToSyncOutbound
CommentScheduled
CommentSyncLog
CustomConfig
CustomEmailTemplateRenderError
EmailToSend
EventLogEntry
ImportedCommentScheduled
ModerationGroup
Moderator
Page
PageReact
PendingVote
QuestionResult
SSOUser
SentEmail
SpamEvent
Tenant
TenantAuditLog
TenantBadge
TenantDailyUsage
TenantInvoiceHistory
TenantPackage
User
UserBadge
UserBadgeProgress
UserNotification
UserSubscription
UserUsage
Vote

Структура журнала аудита

Объект AuditLog представляет собой запись об аудируемом событии для тенантов, у которых есть доступ к этой функции.

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

Структура AuditLog

Copy

interface AuditLog {
    id: string;
    userId?: string;
    username?: string;
    resourceName: string;
    crudType: 'c' | 'r' | 'u' | 'd' | 'login';
    from: string;
    url?: string;
    ip?: string;
    when: string;
    description?: string;
    serverStartDate: string;
    objectDetails?: object;
}

Журнал аудита является неизменяемым. В него также нельзя записывать вручную. Только FastComments.com может решать, когда записывать в журнал аудита. Тем не менее, вы можете читать его через этот API.

События в журнале аудита истекают через два года.

GET /api/v1/audit-logs

Resource: AuditLog as GET /api/v1/audit-logs Credit Cost: 10

Этот API использует пагинацию, обеспечиваемую параметрами skip, before и after. AuditLogs возвращаются страницами по 1000, отсортированными по when и id.

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

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

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

Сортировку можно задать установкой order в ASC или DESC. По умолчанию ASC.

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

Пример cURL запроса AuditLog

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/audit-logs?tenantId=demo&API_KEY=DEMO_API_SECRET&skip=0&order=ASC&before=123&after=456'

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

Copy

interface CommentsRequestQueryParams {
    tenantId: string
    API_KEY: string
    order?: 'ASC' | 'DESC'
    skip?: number
    before?: number
    after?: number
}

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

Copy

interface CommentsResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Включается при ошибке. **/
    reason?: string
    /** Журналы аудита. **/
    auditLogs: AuditLog[]
}

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

Объект Comment представляет комментарий, оставленный пользователем.

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

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

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

Copy

interface Comment {
    /** READONLY: Установлено в true, если система обнаружения спама определила комментарий как спам. **/
    aiDeterminedSpam?: boolean
    /** Показывается ли комментарий. При сохранении комментария устанавливается в true, иначе он будет скрыт. **/
    approved?: boolean
    /** Аватар пользователя. **/
    avatarSrc?: string
    /** Дочерние комментарии. Не заполняется во всех сценариях. Используется, когда через API параметр asTree установлен в true. **/
    children: Comment[]
    /** Оригинальный текст комментария от пользователя. **/
    comment: string
    /** READONLY: Текст комментария, преобразованный в HTML. **/
    commentHTML?: string
    /** Email комментатора. Обязателен, если анонимные комментарии отключены. **/
    commenterEmail?: string
    /** Ссылка комментатора (например, его блог). **/
    commenterLink?: string
    /** Имя комментатора. Всегда обязательно. Если недоступно, установите что-то вроде "Anonymous". **/
    commenterName: string
    /** Дата оставления комментария в виде UTC epoch. **/
    date: number
    /** "Отображаемая метка" для комментария - например "Admin", "Moderator", или что-то вроде "VIP User". **/
    displayLabel?: string
    /** Домен, на котором был опубликован комментарий. **/
    domain?: string
    /** READONLY: Количество пометок (флагов) для комментария. **/
    flagCount?: number
    /** #хэштеги, написанные в комментарии и успешно распарсенные. Также вы можете вручную добавить хэштеги для запроса, но они не будут автоматически отображаться в тексте комментария. **/
    hashTags?: CommentHashTag[]
    /** READONLY: Содержит ли комментарий изображения? **/
    hasImages?: boolean
    /** READONLY: Содержит ли комментарий ссылки? **/
    hasLinks?: boolean
    /** READONLY: Уникальный идентификатор комментария. **/
    id: string
    /** Только при создании! Для хранения значение хешируется. **/
    ip?: string
    /** READONLY: Заблокировал ли текущий пользователь автора этого комментария? **/
    isBlocked?: boolean
    /** READONLY: Автор комментария — администратор? Автоматически определяется по userId. **/
    isByAdmin?: boolean
    /** READONLY: Автор комментария — модератор? Автоматически определяется по userId. **/
    isByModerator?: boolean
    /** Установлено в true, если комментарий был мягко удалён (оставлен заполнитель из-за другой конфигурации). **/
    isDeleted?: boolean
    /** Установлено в true, если аккаунт пользователя был удалён, а комментарий нужно было сохранить. **/
    isDeletedUser?: boolean
    /** READONLY: Отмечен ли комментарий флагом текущего вошедшего пользователя (contextUserId)? **/
    isFlagged?: boolean
    /** Закреплен ли комментарий? **/
    isPinned?: boolean
    /** Заблокирован ли комментарий для новых ответов (модераторы всё ещё могут отвечать)? **/
    isLocked?: boolean
    /** Является ли комментарий спамом? **/
    isSpam?: boolean
    /** READONLY: Проголосовал ли текущий пользователь (contextUserId) против комментария? **/
    isVotedDown?: boolean
    /** READONLY: Проголосовал ли текущий пользователь (contextUserId) за комментарий? **/
    isVotedUp?: boolean
    /** Локаль, на которой написан комментарий. Если не указана, будет определена по HTTP-заголовку Accept-Language. **/
    locale?: 'de_de' | 'en_us' | 'es_es' | 'fr_fr' | 'it_it' | 'ja_jp' | 'ko_kr' | 'pl_pl' | 'pt_br' | 'ru_ru' | 'tr_tr' | 'zh_cn' | 'zh_tw'
    /** READONLY: @упоминания, написанные в комментарии и успешно распарсенные. **/
    mentions?: CommentUserMention[]
    /** Дополнительные метаданные, связанные с комментарием. **/
    meta?: Record<string, string | number | boolean>
    /** Необязательный список идентификаторов групп модерации, связанных с этим комментарием. **/
    moderationGroupIds?: string[]|null
    /** READONLY: Идентификатор объекта голосования, соответствующего голосу текущего пользователя (contextUserId) для этого комментария. **/
    myVoteId?: string
    /** Были ли отправлены уведомления об этом комментарии комментаторам. Чтобы предотвратить отправку уведомлений при импорте, установите это в true. **/
    notificationSentForParent?: boolean
    /** Были ли отправлены уведомления об этом комментарии пользователям тенанта. Чтобы предотвратить отправку уведомлений при импорте, установите это в true. **/
    notificationSentForParentTenant?: boolean
    /** Заголовок страницы, на которой был этот комментарий. **/
    pageTitle?: string
    /** Если мы отвечаем на комментарий, это ID комментария, на который дается ответ. **/
    parentId?: string|null
    /** Отмечен ли комментарий как просмотренный. **/
    reviewed: boolean
    /** Идентификатор тенанта, к которому принадлежит комментарий. **/
    tenantId: string
    /** Пользователь, написавший комментарий. Создаётся автоматически при сохранении комментария с указанием имени/email. **/
    userId?: string|null
    /** URL страницы, где виден этот комментарий, например публикация в блоге. **/
    url: string
    /** "Очищенная" версия urlId, которую вы передали. При сохранении вы указываете это поле, но при получении комментария обратно оно будет "очищено" и ваше исходное значение перемещено в "urlIdRaw". **/
    urlId: string
    /** READONLY: Оригинальный urlId, который вы передали. **/
    urlIdRaw?: string
    /** Проверены ли пользователь и этот комментарий? **/
    verified: boolean
    /** Количество голосов "за". **/
    votesUp?: number
    /** Количество голосов "против". **/
    votesDown?: number
    /** "Карма" комментария (= votes up - votes down). **/
    votes?: number
}

Некоторые из этих полей помечены как READONLY — они возвращаются API, но не могут быть установлены.

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

Комментарии пишутся в варианте markdown от FastComments, который представляет собой markdown плюс традиционные bbcode-подобные теги для изображений, например [img]path[/img].

Текст хранится в двух полях. Текст, введённый пользователем, сохраняется без изменений в поле comment. Он рендерится и сохраняется в поле commentHTML.

Разрешённые HTML-теги: b, u, i, strike, pre, span, code, img, a, strong, ul, ol, li, and br.

Рекомендуется рендерить HTML, так как это очень небольшой поднабор HTML, и создание рендерера довольно простое. Существуют несколько библиотек, например для React Native и Flutter, которые могут в этом помочь

Вы можете выбрать отображение ненормализованного значения из поля comment. Пример парсера находится здесь..

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

Упоминания

Когда пользователи отмечаются в комментарии, информация сохраняется в списке mentions. Каждый объект в этом списке имеет следующую структуру.

Объект упоминания в комментарии

Copy

Run

interface CommentUserMention {
    /** Идентификатор пользователя. Для SSO-пользователей будет добавлен префикс вашего tenant id. **/
    id: string
    /** Финальный текст @упоминания, включая символ @. **/
    tag: string
    /** Оригинальный текст @упоминания, включая символ @. **/
    rawTag: string
    /** Тип отмеченного пользователя. user = аккаунт FastComments.com. sso = SSOUser. **/
    type: 'user'|'sso'
    /** Даже если пользователь отказался от уведомлений, это поле всё равно будет true. **/
    sent: boolean
}

Хэштеги

Когда хэштеги используются и успешно распарсены, информация хранится в списке hashTags. Каждый объект в этом списке имеет следующую структуру. Хэштеги также можно вручную добавить в массив hashTags комментария для запросов, если установлен флаг retain.

Объект хэштега комментария

Copy

Run

interface CommentHashTag {
    /** Идентификатор хэштега. **/
    id: string
    /** Финальный текст #хэштега, включая символ #. **/
    tag: string
    /** Если хэштег связан с кастомным URL, это будет указано. **/
    url?: string
    /** Флаг, указывающий, нужно ли сохранять хэштег, даже если он отсутствует в тексте комментария при его обновлении. Полезно для пометки комментариев без изменения текста. **/
    retain?: boolean
}

GET /api/v1/comments

Resource: Comment as GET /api/v1/comments Credit Cost: 1

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

Pagination

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

Fastest: Precalculated Pagination:
1. Так работает FastComments, когда вы используете наши предустановленные виджеты и клиенты.
2. Нажатие "next" просто увеличивает номер страницы.
3. Вы можете думать об этом как о получении из key-value хранилища.
4. Таким образом, просто определите параметр page, начиная с 0, и направление сортировки в direction.
5. Размеры страниц можно настраивать через правила кастомизации.
Most Flexible: 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

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

Trees Explained

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

Tree Pagination Diagram

Fetching Comments in The Context of a User

API /comments может использоваться в двух контекстах, для разных сценариев использования:

Для возврата комментариев с сортировкой и метаданными для построения собственного клиента.
- В этом случае определите параметр запроса contextUserId.
Для получения комментариев с вашего бэкенда для кастомных интеграций.
- Платформа по умолчанию будет использовать этот сценарий без contextUserId.

Предварительно рассчитанная пагинация комментариев

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&page=0&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR'

Гибкая пагинация комментариев

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10'

Гибкая пагинация комментариев в контексте пользователя

Copy

curl --request GET \
  --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'

Гибкая пагинация комментариев в контексте пользователя только для верхнего уровня

Copy

curl --request GET \
  --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'

Get Comments as a Tree

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

Комментарии как дерево в контексте пользователя

Copy

curl --request GET \
  --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'

Хотите получить только верхнеуровневые комментарии и их непосредственных детей? Вот один из вариантов:

Комментарии как дерево с максимальной глубиной

Copy

curl --request GET \
  --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'

Однако в вашем UI может понадобиться знать, показывать ли кнопку "показать ответы" для каждого комментария. При получении комментариев в виде дерева к комментариям добавляется свойство hasChildren, когда это применимо.

Get Comments as a Tree, Searching by Hash Tag

Можно выполнять поиск по хештегу через API по всему вашему тенанту (не ограничиваясь одной страницей или urlId).

В этом примере мы опускаем urlId и ищем по нескольким хештегам. API вернёт только комментарии, которые содержат все запрошенные хештеги.

Комментарии как дерево в контексте пользователя, по хештегу

Copy

curl --request GET \
  --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'

All Request Params

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

Copy

interface CommentsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** Идентификатор urlId (URL страницы или ID статьи), с которым связаны комментарии. **/
    urlId?: string
    /** Ограничить возвращаемые комментарии этим пользователем. **/
    userId?: string
    /** Используйте для поиска по хештегу. Чтобы получить пересечение нескольких хештегов, используйте &hashTag=a&hashTag=b. **/
    hashTag?: string
    /** Направление сортировки. По умолчанию MR (Most Relevant). Другие опции: OF (Oldest First) и NF (Newest First). **/
    direction?: 'MR' | 'OF' | 'NF'
    /** Precalculated Pagination: The page to fetch, starting with 0. Pass -1 for all comments (up to 250). **/
    page?: number
    /** Flexible Pagination: How many comments should we return? **/
    limit?: number
    /** Flexible Pagination: How many child comments should we return for each parent? **/
    limitChildren?: number
    /** Flexible Pagination: How many comments should we skip? **/
    skip?: number
    /** Flexible Pagination: How many child comments should we skip for each parent? **/
    skipChildren?: number
    /** For determining blocked and flagged comments. **/
    contextUserId?: string
    /** For determining blocked and flagged comments. **/
    anonUserId?: string
    /** For fetching child comments. **/
    parentId?: string
    /** For fetching as a tree. **/
    asTree?: boolean
    /** How far into the tree should we return data? 0 returns no children. 1 returns immediate children, etc. **/
    maxTreeDepth?: number
}

The Response

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

Copy

interface CommentsResponse {
    status: 'success' | 'failed'
    /** Включается в случае ошибки. **/
    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'
    /** Включается в случае ошибки. **/
    reason?: string
    /** Комментарии! **/
    comments: Comment[]
}

Helpful Tips

URL ID

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

Anonymous Actions

Для анонимного комментирования, вероятно, стоит передавать anonUserId при получении комментариев, а также при выполнении пометки и блокировки.

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

Comments Not Being Returned

Проверьте, что ваши комментарии одобрены и не являются спамом.

GET /api/v1/comments/:id

Resource: Comment as GET /api/v1/comments/:id Credit Cost: 1

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

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

Copy

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

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

Copy

interface CommentsGetByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Структура ответа при получении комментария по id

Copy

interface CommentGetByIdResponse {
    status: 'success' | 'failed'
    /** Указывается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'missing-id'
    /** Указывается при ошибке. **/
    reason?: string
    /** Комментарий! **/
    comment?: Comment
}

POST /api/v1/comments

Resource: Comment as POST /api/v1/comments Credit Cost: 1

This API endpoint provides the ability to create comments.

Common use cases are custom UIs, integrations, or imports.

Notes:

This API can update the comment widget "live" if desired (this increases creditsCost from 1 to 2).
This API will automatically create user objects in our system if email is provided.
Trying to save two comments with different emails, but the same username, will result in an error for the second comment.
If you are specifying parentId, and a child comment has notificationSentForParent as false, we will send notifications for the parent comment. This is done every hour (we batch the notifications together to decrease the number of emails sent).
If you want to send welcome emails when creating users, or comment verification emails, set sendEmails to true in query parameters.
Comments created via this API will show up in the Analytics and Moderation pages of the admin app.
"bad words" are still masked in the commenter names and comment text if the setting is turned on.
Comments created via this API can still be checked for spam if desired.
Configuration such as max comment length, if configured via the Customization Rule admin page, will apply here.

The minimum data required to submit that will show in the comment widget, is as follows:

Минимальный пример cURL-запроса для отправки комментария (POST)

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true' \
  --header 'Content-Type: application/json' \
  --data '{
    "approved": true,
    "comment": "some-comment",
    "commenterName": "some-commenter-name",
    "date": 1622644382148,
    "urlId": "some-place",
    "url": "https://exmaple.com/some-page",
    "verified": true
}'

A more realistic request may look like:

Пример cURL-запроса для отправки комментария (POST)

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true&doSpamCheck=true' \
  --header 'Content-Type: application/json' \
  --data '{
    "approved": true,
    "avatarSrc": "https://static.fastcomments.com/1605337537848-DSC_0841.JPG",
    "comment": "some-comment",
    "commenterName": "some-commenter-name",
    "commenterEmail": "fordperfect@spaceship.com",
    "date": 1622644382148,
    "isSpam": false,
    "locale": "en_us",
    "notificationSentForParent": true,
    "notificationSentForParentTenant": true,
    "reviewed": true,
    "urlId": "some-place",
    "url": "https://exmaple.com/some-page",
    "verified": true,
    "votes": 1,
    "votesUp": 2,
    "votesDown": 1,
    "ip": "123.456.789.000"
}'

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

Copy

interface CommentPostQueryParams {
    tenantId: string
    API_KEY: string
    doSpamCheck?: 'true' | 'false'
    /** Показывать ли комментарий "live" пользователям, просматривающим экземпляры виджета комментариев с тем же urlId. ПРИМЕЧАНИЕ: Удваивает стоимость в кредитах с 1 до 2. **/
    isLive?: 'true' | 'false'
    sendEmails?: 'true' | 'false'
    populateNotifications?: 'true' | 'false'
}

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

Copy

interface CommentPostResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    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';
    /** Включается при ошибке. **/
    reason?: string
    /** Созданный комментарий. **/
    comment?: Comment
    /** Связанный пользователь, который мог существовать ранее или быть создан новым. **/
    user?: User
}

PATCH /api/v1/comments/:id

Resource: Comment as PATCH /api/v1/comments/:id Credit Cost: 1

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

Notes:

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

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

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true' \
  --header 'Content-Type: application/json' \
  --data '{
    "comment": "some-new-comment-text"
}'

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

Copy

interface CommentPatchQueryParams {
    tenantId: string
    API_KEY: string
    /** Пользователь, выполняющий обновление. При необходимости может быть использован для проверки возможности редактирования комментария.  **/
    contextUserId?: string
    /** Проверять ли, выглядит ли новый комментарий как спам?  **/
    doSpamCheck?: 'true' | 'false'
    /** Появляться ли комментарий "вживую" для пользователей, просматривающих экземпляры виджета комментариев с таким же urlId. ПРИМЕЧАНИЕ: удваивает стоимость в кредитах с 1 до 2. **/
    isLive?: 'true' | 'false'
}

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

Copy

interface CommentPatchResponse {
    status: 'success' | 'failed'
    /** Указывается при ошибке. **/
    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'
    /** Указывается при ошибке. **/
    reason?: string
}

DELETE /api/v1/comments/:id

Resource: Comment as DELETE /api/v1/comments/:id Credit Cost: 1

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

Примечания:

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

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

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json'

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

Copy

interface CommentDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** Пользователь, выполняющий обновление. При необходимости может использоваться для проверки права удалить комментарий.  **/
    contextUserId?: string
    /** Указывает, следует ли удалить комментарий "live" у пользователей, просматривающих экземпляры виджета комментариев с тем же urlId. NOTE: Удваивает стоимость в кредите с 1 до 2. **/
    isLive?: 'true' | 'false'
}

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

Copy

interface CommentDeleteResponse {
    status: 'success' | 'failed'
    /** Указывается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Указывается при ошибке. **/
    reason?: string
}

POST /api/v1/comments/:id/flag

Resource: Comment as POST /api/v1/comments/:id/flag Credit Cost: 1

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

Примечания:

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

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

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/flag?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \
  --header 'Content-Type: application/json'

Для анонимной пометки необходимо указать anonUserId. Это может быть идентификатор, который представляет анонимную сессию, или случайный UUID. Это позволяет поддерживать пометку и снятие пометки с комментариев даже если пользователь не вошёл в систему. Так комментарий может быть помечен как flagged при получении комментариев с тем же anonUserId.

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

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/flag?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \
  --header 'Content-Type: application/json'

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

Copy

interface CommentFlagQueryParams {
    tenantId: string
    API_KEY: string
    userId?: string
    anonUserId?: string
}

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

Copy

interface CommentFlagResponse {
    status: 'success' | 'failed'
    /** Включается при неудаче. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id'
    /** Включается при неудаче. **/
    reason?: string
    /** Комментарий был снят с одобрения (скрыт) из‑за слишком большого количества пометок? **/
    wasUnapproved?: boolean;
}

POST /api/v1/comments/:id/un-flag

Resource: Comment as POST /api/v1/comments/:id/un-flag Credit Cost: 1

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

Примечания:

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

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

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-flag?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \
  --header 'Content-Type: application/json'

Для анонимного флагирования мы должны указать anonUserId. Это может быть идентификатор, представляющий анонимную сессию, или случайный UUID.

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

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-flag?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \
  --header 'Content-Type: application/json'

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

Copy

interface CommentFlagQueryParams {
    tenantId: string
    API_KEY: string
    userId?: string
    anonUserId?: string
}

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

Copy

interface CommentUnFlagResponse {
    status: 'success' | 'failed'
    /** Указывается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id'
    /** Указывается при ошибке. **/
    reason?: string
}

POST /api/v1/comments/:id/block

Resource: Comment as POST /api/v1/comments/:id/block Credit Cost: 1

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

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

Примечания:

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

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

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/block?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \
  --header 'Content-Type: application/json'

Для анонимной блокировки необходимо указать anonUserId. Это может быть идентификатор, представляющий анонимную сессию, или случайный UUID. Это позволяет поддерживать блокировку комментариев даже если пользователь не вошёл в систему, получая комментарии с тем же anonUserId.

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

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/block?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \
  --header 'Content-Type: application/json'

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

Copy

interface CommentBlockQueryParams {
    tenantId: string
    API_KEY: string
    userId?: string
    anonUserId?: string
    commentIdsToCheck?: string[]
}

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

Copy

interface CommentBlockResponse {
    status: 'success' | 'failed'
    /** Указывается при ошибке. **/
    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'
    /** Указывается при ошибке. **/
    reason?: string
    /** Если определен commentIdsToCheck, элементы этой карты со значением true также считаются заблокированными. **/
    commentStatuses?: Record<string, boolean>;
}

POST /api/v1/comments/:id/un-block

Resource: Comment as POST /api/v1/comments/:id/un-block Credit Cost: 1

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

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

Примечания:

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

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

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-block?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \
  --header 'Content-Type: application/json'

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

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-block?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \
  --header 'Content-Type: application/json'

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

Copy

interface CommentUnBlockQueryParams {
    tenantId: string
    API_KEY: string
    userId?: string
    anonUserId?: string
    commentIdsToCheck?: string[]
}

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

Copy

interface CommentUnBlockResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    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'
    /** Включается при ошибке. **/
    reason?: string
    /** Если определен commentIdsToCheck, записи в этой карте со значением true остаются заблокированными. Если false, возможно, стоит снова показать комментарии пользователю, чтобы ему не пришлось обновлять страницу. **/
    commentStatuses?: Record<string, boolean>;
}

Структура шаблона письма

Объект EmailTemplate представляет конфигурацию для пользовательского шаблона электронной почты для тенанта.

Система будет выбирать шаблон электронной почты по:

Его идентификатору типа, мы называем это emailTemplateId. Они являются константами.
domain. Сначала мы попытаемся найти шаблон для домена, к которому привязан связанный объект (например, Comment), и если совпадение не найдено, то попытаемся найти шаблон, где domain равен null или *.

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

Структура шаблона электронной почты

Copy

interface EmailTemplate {
    id: string
    tenantId: string
    emailTemplateId: string
    displayName: string
    /** ТОЛЬКО ДЛЯ ЧТЕНИЯ **/
    createdAt: string
    /** ТОЛЬКО ДЛЯ ЧТЕНИЯ **/
    updatedAt: string
    /** ТОЛЬКО ДЛЯ ЧТЕНИЯ **/
    updatedByUserId: string
    /** Домен, с которым должен быть связан шаблон. **/
    domain?: string | '*' | null
    /** Содержимое шаблона письма в синтаксисе EJS. **/
    ejs: string
    /** Отображение переопределённых ключей переводов в значения для каждого поддерживаемого языка. **/
    translationOverridesByLocale: Record<string, Record<string, string>>
    /** Объект, представляющий контекст рендеринга шаблона. **/
    testData: object
}

Примечания

Вы можете получить допустимые значения emailTemplateId через endpoint /definitions.
Endpoint /definitions также содержит переводы по умолчанию и тестовые данные.
Сохранение шаблона не удастся при неверной структуре или некорректных тестовых данных.

GET /api/v1/email-templates/:id

Resource: EmailTemplate as GET /api/v1/email-templates/:id Credit Cost: 1

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

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

Copy

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

Структура запроса EmailTemplate по ID

Copy

interface EmailTemplatesByIdRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Структура ответа EmailTemplate по ID

Copy

interface EmailTemplateResponse {
    status: 'success' | 'failed'
    /** Включается в случае ошибки. **/
    code?: 'internal' | 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found'
    /** Включается в случае ошибки. **/
    reason?: string
    emailTemplate?: EmailTemplate | null
}

GET /api/v1/email-templates

Resource: EmailTemplate as GET /api/v1/email-templates Credit Cost: 1

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

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

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/email-templates?tenantId=demo&page=0&API_KEY=DEMO_API_SECRET'

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

Copy

interface EmailTemplatesRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** Страница для получения, начинается с 0. **/
    page: number
}

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

Copy

interface EmailTemplatesResponse {
    status: 'success' | 'failed'
    /** Присутствует в случае ошибки. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Присутствует в случае ошибки. **/
    reason?: string
    emailTemplates: EmailTemplate[]
}

PATCH /api/v1/email-templates/:id

Resource: EmailTemplate as PATCH /api/v1/email-templates/:id Credit Cost: 1

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

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

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

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

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/email-templates/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "displayName": "Some New Name",
}'

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

Copy

interface EmailTemplatePatchQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface EmailTemplatePatchResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    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';  
    /** Включается при ошибке. **/
    reason?: string
    /** Обновлённый шаблон письма. **/
    emailTemplate?: EmailTemplate
}

POST /api/v1/email-templates

Resource: EmailTemplate as POST /api/v1/email-templates Credit Cost: 1

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

Примечания:

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

Минимальные данные, необходимые для добавления шаблона, приведены ниже:

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

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/email-templates?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "emailTemplateId": "comment-user-mention",
    "displayName": "I'm a custom template.",
    "ejs": "This is an @mention notification! My name is <%= comment.commenterName %>."
}'

Возможно, вы захотите иметь шаблоны для каждого сайта, в этом случае вы задаёте domain:

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

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/email-templates?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "emailTemplateId": "comment-user-mention",
    "displayName": "I'm a custom template.",
    "ejs": "This is some email content!",
    "domain": "somespecificsite.com",
}'

Структура POST-запроса EmailTemplate

Copy

interface EmailTemplatePostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура POST-ответа EmailTemplate

Copy

interface EmailTemplatePostResponse {
    status: 'success' | 'failed'
    /** Указывается при ошибке. **/
    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';
    /** Указывается при ошибке. **/
    reason?: string
    /** Созданный шаблон. **/
    emailTemplate?: EmailTemplate
}

POST /api/v1/email-templates/render

Resource: EmailTemplate as POST /api/v1/email-templates/render Credit Cost: 1

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

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

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/email-templates/render?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "emailTemplateId": "comment-user-mention",
    "displayName": "I'm a custom template.",
    "ejs": "This is an @mention notification! My name is <%= comment.commenterName %>."
}'

Структура POST-запроса EmailTemplate

Copy

interface EmailTemplatePostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура POST-ответа EmailTemplate

Copy

interface EmailTemplatePostResponse {
    status: 'success' | 'failed'
    /** Присутствует при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'unexpected-param' | 'does-not-render';
    /** Присутствует при ошибке. **/
    reason?: string
    /** Отрендеренный HTML при успешном выполнении. **/
    html?: string
}

DELETE /api/v1/email-templates/:id

Resource: EmailTemplate as DELETE /api/v1/email-templates/:id Credit Cost: 1

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

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

Copy

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

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

Copy

interface EmailTemplateRequestQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface EmailTemplateDeleteResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized'
    /** Включается при ошибке. **/
    reason?: string
}

Структура хэштега

Объект HashTag представляет собой метку, которую может оставить пользователь. HashTags могут использоваться для ссылки на внешний фрагмент контента или для объединения связанных комментариев.

The structure for the HashTag object is as follows:

Структура HashTag

Copy

interface HashTag {
    /** Должен начинаться с "#" или другого желаемого символа. **/
    tag: string
    /** Необязательный URL, на который может указывать хэштег. Вместо фильтрации комментариев по хэштегу интерфейс перенаправит на этот URL при клике. **/
    url?: string
    /** ТОЛЬКО ДЛЯ ЧТЕНИЯ **/
    createdAt: string
}

Notes:

In some API endpoints you will see that the hashtag is used in the URL. Remember to URI-Encoded values. For example, # should instead be represented as %23.
Some of these fields are marked READONLY - these are returned by the API but cannot be set.

GET /api/v1/hash-tags

Resource: HashTag as GET /api/v1/hash-tags Credit Cost: 1

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

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

Copy

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

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

Copy

interface HashTagsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** Страница для получения, начиная с 0. **/
    page: number
}

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

Copy

interface HashTagsResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Включается при ошибке. **/
    reason?: string
    /** Хэштеги! **/
    hashTags: HashTag[]
}

PATCH /api/v1/hash-tags/:tag

Resource: HashTag as PATCH /api/v1/hash-tags/:tag Credit Cost: 1

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

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

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/hash-tags/%23example_hash_tag?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com/some-`page`"
}'

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

Copy

interface HashTagPatchQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface HashTagPatchResponse {
    status: 'success' | 'failed'
    /** Указывается при неудаче. **/
    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'
    /** Указывается при неудаче. **/
    reason?: string
    hashTag?: HashTag; // Мы возвращаем полностью обновлённый HashTag при успехе.
}

POST /api/v1/hash-tags

Resource: HashTag as POST /api/v1/hash-tags Credit Cost: 1

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

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

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/hash-tags?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "tag": "#example",
    "url": "https://example.com/some-page"
}'

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

Copy

interface HashTagPostQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface HashTagPostResponse {
    status: 'success' | 'failed'
    /** Включено при ошибке. **/
    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'
    /** Включено при ошибке. **/
    reason?: string
    hashTag?: HashTag; // При успешном выполнении возвращается полностью созданный хештег.
}

POST /api/v1/hash-tags/bulk

Resource: HashTag as POST /api/v1/hash-tags/bulk Credit Cost: 1

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

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

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/hash-tags/bulk?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "tags": [
        {
            "tag": "#example",
            "url": "https://example.com/some-page"
        }
    ]
}'

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

Copy

interface HashTagPostQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface HashTagBulkPostResponse {
    status: 'success' | 'failed'
    /** Присутствует в случае ошибки. **/
    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'
    /** Присутствует в случае ошибки. **/
    reason?: string
    results?: HashTagPostResponse[]; // Мы возвращаем список объектов HashTagPostResponse для каждого указанного тега.
}

DELETE /api/v1/hash-tags/:tag

Resource: HashTag as DELETE /api/v1/hash-tags/:tag Credit Cost: 1

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

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

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

Copy

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

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

Copy

interface HashTagDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface HashTagDeleteResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist'
    /** Включается при ошибке. **/
    reason?: string
}

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

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

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

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

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

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

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

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

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

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

Структура Moderator

Copy

interface Moderator {
    name: string
    email: string
    tenantId: string
    userId?: string|null
    acceptedInvite?: boolean
    markReviewedCount?: number
    deletedCount?: number
    markedSpamCount?: number
    approvedCount?: number
    editedCount?: number
    bannedCount?: number
    createdAt: string
    moderationGroupIds?: string[]|null
}

GET /api/v1/moderators/:id

Resource: Moderator as GET /api/v1/moderators/:id Credit Cost: 1

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

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

Copy

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

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

Copy

interface ModeratorByIdQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface ModeratorByIdResponse {
    status: 'success' | 'failed'
    /** Указывается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Указывается при ошибке. **/
    reason?: string
    moderator?: Moderator
}

GET /api/v1/moderators

Resource: Moderator as GET /api/v1/moderators Credit Cost: 1

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

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

Пример cURL для Moderator

Copy

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

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

Copy

interface ModeratorsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** Количество модераторов для пропуска при постраничной навигации. **/
    skip?: number
}

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

Copy

interface ModeratorsResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Включается при ошибке. **/
    reason?: string
    moderators?: Moderator[]
}

PATCH /api/v1/moderators/:id

Resource: Moderator as PATCH /api/v1/moderators/:id Credit Cost: 1

Этот конечный пункт API предоставляет возможность обновить Moderator по id.

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

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

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

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/moderators/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some New Name",
}'

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

Copy

interface ModeratorPatchQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface ModeratorPatchResponse {
    status: 'success' | 'failed'
    /** Включается при неудаче. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'name-required' | 'email-required' | 'unexpected-param' | 'not-found';  
    /** Включается при неудаче. **/
    reason?: string
}

POST /api/v1/moderators

Resource: Moderator as POST /api/v1/moderators Credit Cost: 1

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

При создании Moderator действуют следующие ограничения:

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

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

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

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/moderators?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some Name",
    "email": "someone@someone.com"
}'

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

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

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/moderators?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some Name",
    "email": "someone@someone.com",
    "userId": "some-tenant-user-id"
}'

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

Copy

interface ModeratorPostQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface ModeratorPostResponse {
    status: 'success' | 'failed'
    /** Указывается в случае ошибки. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'name-required' | 'email-required' | 'unexpected-param' | 'not-found'
    /** Указывается в случае ошибки. **/
    reason?: string
    moderator?: Moderator; // В случае успеха возвращаем полностью созданного модератора.
}

POST /api/v1/moderators/:id/send-invite

Resource: Moderator as POST /api/v1/moderators/:id/send-invite Credit Cost: 10

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

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

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

Примечания:

Если пользователь с указанным email уже существует, ему будет отправлено приглашение модерировать комментарии вашего тенанта.
Если пользователь с указанным email не существует, ссылка-приглашение проведёт его через создание аккаунта.
Приглашение истечёт через 30 days.

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

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

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/moderators/xyz/send-invite?tenantId=demo&API_KEY=DEMO_API_SECRET&fromName=Bob' \
  --header 'Content-Type: application/json'

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

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

Copy

interface ModeratorSendInviteQueryParams {
    tenantId: string
    API_KEY: string
    /** Письмо, отправленное пользователю, будет выглядеть так, будто оно отправлено от этого имени. **/
    fromName: string
}

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

Copy

interface ModeratorSendInviteResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'not-found | 'from-name-required' | 'from-name-invalid'
    /** Включается при ошибке. **/
    reason?: string
}

DELETE /api/v1/moderators/:id

Resource: Moderator as DELETE /api/v1/moderators/:id Credit Cost: 5

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

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

Copy

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

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

Copy

interface ModeratorDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface ModeratorDeleteResponse {
    status: 'success' | 'failed'
    /** Указывается при неудаче. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found'
    /** Указывается при неудаче. **/
    reason?: string
}

Структура счётчика уведомлений

Объект NotificationCount представляет количество непрочитанных уведомлений и метаданные для пользователя.

Если нет непрочитанных уведомлений, для пользователя не будет объекта NotificationCount.

Объекты NotificationCount создаются автоматически и не могут быть созданы через API. Они также истекают через год.

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

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

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

Copy

interface NotificationCount {
    id: string // идентификатор пользователя
    count: number
    createdAt: string // строка с датой
    expireAt: string // строка с датой
}

GET /api/v1/notification-count/:user_id

Resource: NotificationCount as GET /api/v1/notification-count/:user_id Credit Cost: 1

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

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

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

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

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/notification-count/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
# -> {"status":"success","data":{"count":1,"createdAt":"2023-03-06T18:45:01.726Z","expireAt":"2024-03-06T01:25:01.726Z","id":"example"}}

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

Copy

interface NotificationCountGetQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface NotificationCountGetResponse {
    status: 'success' | 'failed'
    /** Указывается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'not-found'
    /** Указывается при ошибке. **/
    reason?: string
    data?: NotificationCount
}

DELETE /api/v1/notification-count/:user_id

Resource: NotificationCount as DELETE /api/v1/notification-count/:user_id Credit Cost: 1

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

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

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

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/notification-count/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
# -> {"status":"success"}

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

Copy

interface NotificationCountDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface NotificationCountDeleteResponse {
    status: 'success' | 'failed'
    /** Указывается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'not-found'
    /** Указывается при ошибке. **/
    reason?: string
}

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

Объект Notification представляет уведомление для пользователя.

Notification объекты создаются автоматически и не могут быть созданы через API. Они также истекают через год. Уведомления не могут быть удалены. Однако их можно обновлять, устанавливая viewed в false, и вы можете выполнять запросы по полю viewed.

Пользователь также может отписаться от уведомлений для конкретного комментария, установив optedOut в уведомлении в true. Вы можете снова подписаться, установив его в false.

Существуют разные типы уведомлений — смотрите relatedObjectType и type.

Механизмы создания уведомлений довольно гибкие и могут быть вызваны множеством сценариев (см. NotificationType).

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

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

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

Copy

enum NotificationObjectType {
    Comment = 0,
    Profile = 1,
    Tenant = 2
}
enum NotificationType {
    /** Если кто-то ответил вам. **/
    RepliedToMe = 0,
    /** Если кто-то ответил где-либо в ветке обсуждения (включая ответы на ответы) темы, в которой вы оставили комментарий. **/
    RepliedTransientChild = 1,
    /** Если ваш комментарий был оценён положительно. **/
    VotedMyComment = 2,
    /** Если на корне страницы, на которую вы подписаны, оставлен новый комментарий. **/
    SubscriptionReplyRoot = 3,
    /** Если кто-то прокомментировал ваш профиль. **/
    CommentedOnProfile = 4,
    /** Если у вас есть личное сообщение. **/
    DirectMessage = 5,
    /** TrialLimits предназначен только для пользователей тенанта. **/
    TrialLimits = 6,
    /** Если вас упомянули. **/
    Mentioned = 7
}
interface Notification {
    id: string
    tenantId: string
    /** При SSO идентификатор пользователя имеет формат `<tenant id>:<user id>`. **/
    userId?: string
    /** При работе с SSO вам нужно учитывать только `userId`. **/
    anonUserId?: string
    /** urlId почти всегда определён. Он является необязательным только для уведомлений на уровне тенанта, которые случаются редко. **/
    urlId?: string
    /** URL кешируется для быстрого перехода к источнику уведомления. **/
    url?: string
    /** Заголовок страницы кешируется для быстрого ознакомления с источником уведомления. **/
    pageTitle?: string
    relatedObjectType: NotificationObjectType
    /** Например, идентификатор комментария. **/
    relatedObjectId: string
    viewed: boolean
    createdAt: string // строка даты
    type: NotificationType
    fromCommentId?: string
    fromVoteId?: string
    /** fromUserName и fromUserAvatarSrc кешируются здесь для быстрого отображения уведомления. Они обновляются при обновлении пользователя. **/
    fromUserName: string
    fromUserId: string
    fromUserAvatarSrc?: string
    /** Установите это в true, чтобы перестать получать уведомления для этого объекта. **/
    optedOut?: boolean
}

GET /api/v1/notifications

Resource: Notification as GET /api/v1/notifications Credit Cost: 1

Этот маршрут возвращает до 30 объектов Notification, отсортированных по createdAt, сначала самые новые.

Вы можете фильтровать по userId. При SSO идентификатор пользователя имеет формат <tenant id>:<user id>.

Пример cURL запроса непрочитанных уведомлений для пользователя

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/notifications?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=SOME_USER_ID&viewed=false'

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

Copy

interface NotificationsGetQueryParams {
    tenantId: string
    API_KEY: string
    /** Пагинация путём пропуска записей. **/
    skip?: number
    /** Фильтр по пользователю. **/
    userId?: string
    /** Фильтр по urlId. **/
    urlId?: string
    /** Фильтр по исходному комментарию. **/
    fromCommentId?: string
    /** Фильтр по прочитанным/непрочитанным. **/
    viewed?: 'true' | 'false'
    /** Фильтр по типу. **/
    type?: NotificationType
}

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

Copy

interface NotificationsGetResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Включается при ошибке. **/
    reason?: string
    notifications?: Notification[]
}

GET /api/v1/notifications/count

Resource: Notification as GET /api/v1/notifications/count Credit Cost: 2

Этот маршрут возвращает объект, содержащий количество уведомлений в параметре count.

Он медленнее, чем /notification-count/, и стоит вдвое больше кредитов, но позволяет фильтровать по большему числу параметров.

Вы можете фильтровать по тем же параметрам, что и у эндпоинта /notifications, например userId. При SSO идентификатор пользователя имеет формат <tenant id>:<user id>.

Пример cURL: количество непрочитанных уведомлений для пользователя

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/notifications/count?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=SOME_USER_ID&viewed=false'

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

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/notifications/count?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=SOME_USER_ID&viewed=false&urlId=some-article-id-or-url'

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

Copy

interface NotificationCountGetQueryParams {
    tenantId: string
    API_KEY: string
    /** Фильтрация по пользователю. **/
    userId?: string
    /** Фильтрация по urlId. **/
    urlId?: string
    /** Фильтрация по исходному комментарию. **/
    fromCommentId?: string
    /** Фильтрация по прочитанным/непрочитанным. **/
    viewed?: 'true' | 'false'
    /** Фильтрация по типу. **/
    type?: NotificationType
}

Структура ответа для подсчёта уведомлений

Copy

interface NotificationCountGetResponse {
    status: 'success' | 'failed'
    /** Присутствует при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Присутствует при ошибке. **/
    reason?: string
    count?: number
}

PATCH /api/v1/notifications/:id

Resource: Notification as PATCH /api/v1/notifications/:id Credit Cost: 1

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

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

Вы можете обновлять только следующие поля:
- viewed
- optedOut

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

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/notifications/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "viewed": false,
}'

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

Copy

interface NotificationPatchQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface NotificationPatchResponse {
    status: 'success' | 'failed'
    /** Присутствует при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'unauthorized' | 'not-found';  
    /** Присутствует при ошибке. **/
    reason?: string
}

Структура страницы

Объект Page представляет страницу, к которой могут относиться многие комментарии. Эта связь определяется urlId.

Объект Page хранит информацию, такую как заголовок страницы, количество комментариев и urlId.

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

Структура страницы

Copy

interface Page {
    id: string
    urlId: string
    url: string
    title?: string
    createdAt: string
    commentCount: number
    rootCommentCount: number
    /** Установка этого в null означает, что все пользователи SSO могут видеть страницу. Пустой список означает, что она закрыта для всех пользователей. **/
    accessibleByGroupIds?: string[] | null
    /** Закрыта ли эта страница для новых комментариев? **/
    isClosed?: boolean
}

GET /api/v1/pages

Resource: Page as GET /api/v1/pages Credit Cost: 10

В настоящее время вы можете получить только все страницы (или одну страницу через /by-url-id), связанные с вашей учетной записью. Если вам нужен более точный поиск, свяжитесь с нами.

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

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/pages?tenantId=demo&API_KEY=DEMO_API_SECRET'

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

Copy

interface PagesRequestQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface PagesResponse {
    status: 'success' | 'failed'
    /** Присутствует в случае ошибки. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Присутствует в случае ошибки. **/
    reason?: string
    pages: Page[]
}

Полезный совет

The Comment API requires a urlId. You can call the Pages API first, to see what the urlId values available to you look like.

GET /api/v1/pages/by-url-id

Resource: Page as GET /api/v1/pages/by-url-id Credit Cost: 1

Окремі сторінки можна отримати за їх відповідним urlId. Це може бути корисно для пошуку заголовків сторінок або кількості коментарів.

Пример cURL запроса страницы по URL ID

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/pages/by-url-id?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=example-id-or-url'

Структура запроса страницы по URL ID

Copy

interface PagesRequestQueryParams {
    tenantId: string
    API_KEY: string
    urlId: string
}

Структура ответа страницы по URL ID

Copy

interface PagesResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id'
    /** Включается при ошибке. **/
    reason?: string
    page?: Page[] | null
}

Полезный совет

Не забудьте кодировать в URI значения, такие как urlId.

PATCH /api/v1/pages/:id

Resource: Page as PATCH /api/v1/pages/:id Credit Cost: 1

Этот маршрут предоставляет возможность обновить одну Page. Соответствующие комментарии будут обновлены.

Пример cURL-запроса обновления страницы

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/pages/my-page-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com/some-page"
}'

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

Copy

interface PagePatchQueryParams {
    tenantId: string
    API_KEY: string
}

Структура ответа обновления страницы

Copy

interface PagePatchResponse {
    status: 'success' | 'failed'
    /** Указывается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'missing-id' | 'page-does-not-exist' | 'empty-request' | 'internal' | 'invalid-input' | 'invalid-title' | 'extra-params' | 'accessible-by-group-ids-not-array' | 'too-many-group-ids' | 'group-id-too-large'
    /** Указывается при ошибке. **/
    reason?: string
    user?: Page; // При успешном выполнении возвращаем полностью обновлённую страницу.
}

Примечание

Некоторые параметры в объекте Page обновляются автоматически. Это — счетчики и атрибуты title. Счетчики нельзя изменить через API, так как они являются вычисляемыми значениями. title страницы можно задать через API, но он будет перезаписан, если виджет комментариев используется на странице с тем же urlId и другим заголовком страницы.

POST /api/v1/pages

Resource: Page as POST /api/v1/pages Credit Cost: 1

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

Обычный сценарий использования — контроль доступа.

Примечания:

Если вы оставляли комментарий в треде, или вызывали API для создания Comment, вы уже создали объект Page! Вы можете попробовать получить его через /by-url-id Page маршрут, передав тот же urlId, который был передан виджету комментариев.
Структура Page содержит некоторые вычисляемые значения. В настоящее время это commentCount и rootCommentCount. Они заполняются автоматически и не могут быть установлены через API. Попытка сделать это приведёт к ошибке API.

Пример cURL запроса Page POST

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/pages?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Test Page",
    "url": "some0-url",
    "urlId": "page2",
    "accessibleByGroupIds": ["SOME_GROUP_ID"]
}'

Структура запроса Page POST

Copy

interface PagePostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура ответа Page POST

Copy

interface PagePostResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-request' | 'internal' | 'invalid-input' | 'invalid-title' | 'extra-params' | 'accessible-by-group-ids-not-array' | 'too-many-group-ids' | 'group-id-too-large';  
    /** Включается при ошибке. **/
    reason?: string
    /** Созданная страница. **/
    page?: Page
}

DELETE /api/v1/pages/:id

Resource: Page as DELETE /api/v1/pages/:id Credit Cost: 1

Этот маршрут позволяет удалить одну страницу по её id.

Учтите, что взаимодействие с виджетом комментариев на странице с тем же urlId просто автоматически воссоздаст Page.

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

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/pages/some-page-id?tenantId=demo&API_KEY=DEMO_API_SECRET'

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

Copy

interface PageDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Структура ответа при удалении страницы

Copy

interface PageDeleteResponse {
    status: 'success' | 'failed'
    /** Включается при неудаче. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'page-does-not-exist'
    /** Включается при неудаче. **/
    reason?: string
}

Структура ожидающего события вебхука

A PendingWebhookEvent object represents a queued webhook event that is pending.

PendingWebhookEvent objects are created automatically and cannot be manually created via the API. They also expire after one year. They can be deleted which removes the task from the queue.

There are different event types - check eventType (OutboundSyncEventType) and type (OutboundSyncType).

A common use case for this API is to implement custom monitoring. You may want to call the /count endpoint periodically to poll the outstanding count for given filters.

The structure for the PendingWebhookEvent object is as follows:

Структура PendingWebhookEvent

Copy

enum OutboundSyncEventType {
    Create: 0,
    Delete: 1,
    Update: 2
}
enum OutboundSyncType {
    /** Синхронизационная задача, специфичная для WordPress. **/
    WP: 0,
    Webhook: 1
}
interface PendingWebhookEvent {
    id: string
    /** Идентификатор комментария, связанный с событием. **/
    commentId: string
    /** Объект комментария для события на момент его возникновения. Мы начали добавлять их в ноябре 2023 г. **/
    comment: Comment
    /** Внешний идентификатор, который может быть связан с комментарием. **/
    externalId: string | null
    createdAt: Date
    tenantId: string
    attemptCount: number
    /** Устанавливается перед первой попыткой и после каждой неудачи. **/
    nextAttemptAt: Date
    /** Тип события: создание, удаление или обновление... **/
    eventType: OutboundSyncEventType
    /** Тип синхронизации для выполнения (WordPress, вызов API, и т.д.). **/
    type: OutboundSyncType
    /** Домен, совпавший с комментарием. Мы используем этот домен для выбора API-ключа. **/
    domain: string
    /** Последняя произошедшая ошибка. Этот тип не типизирован и представляет собой "дамп" случившегося. Обычно он содержит объект с полями statusCode, body и картой headers. **/
    lastError: object | null
}

GET /api/v1/pending-webhook-events

Resource: PendingWebhookEvent as GET /api/v1/pending-webhook-events Credit Cost: 2

Этот маршрут возвращает список ожидающих webhook-событий в параметре pendingWebhookEvents.

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

Пример cURL для PendingWebhookEvent

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/pending-webhook-events?tenantId=demo&API_KEY=DEMO_API_SECRET'

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

Copy

interface PendingWebhookEventsGetQueryParams {
    tenantId: string
    API_KEY: string
    commentId?: string
    externalId?: string
    eventType?: OutboundSyncEventType
    type?: OutboundSyncType
    domain?: string
    /** Запрос событий с количеством попыток больше указанного числа. **/
    attemptCountGT?: number
}

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

Copy

interface PendingWebhookEventsGetResponse {
    status: 'success' | 'failed'
    /** Указывается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Указывается при ошибке. **/
    reason?: string
    pendingWebhookEvents?: PendingWebhookEvent[]
}

GET /api/v1/pending-webhook-events/count

Resource: PendingWebhookEvent as GET /api/v1/pending-webhook-events/count Credit Cost: 2

Этот маршрут возвращает объект, содержащий количество ожидающих webhook-событий в параметре count.

Вы можете фильтровать по тем же параметрам, что и у эндпоинта /pending-webhook-events

Пример cURL запроса подсчёта PendingWebhookEvent

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/pending-webhook-events/count?tenantId=demo&API_KEY=DEMO_API_SECRET'

Структура запроса для подсчёта PendingWebhookEvent

Copy

interface PendingWebhookEventsCountQueryParams {
    tenantId: string
    API_KEY: string
    commentId?: string
    externalId?: string
    eventType?: OutboundSyncEventType
    type?: OutboundSyncType
    domain?: string
    /** Запрос событий с количеством попыток больше указанного. **/
    attemptCountGT?: number
}

Структура ответа для подсчёта PendingWebhookEvent

Copy

interface PendingWebhookEventsCountResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Включается при ошибке. **/
    reason?: string
    count?: number
}

DELETE /api/v1/pending-webhook-events/:id

Resource: PendingWebhookEvent as DELETE /api/v1/pending-webhook-events/:id Credit Cost: 1

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

Если необходимо выполнить массовое удаление, вызовите GET API с пагинацией, а затем последовательно вызывайте этот API.

DELETE PendingWebhookEvent — пример cURL-запроса

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/pending-webhook-events/some-id?tenantId=demo&API_KEY=DEMO_API_SECRET'

Структура запроса Delete PendingWebhookEvent

Copy

interface PendingWebhookEventDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Структура ответа Delete PendingWebhookEvent

Copy

interface PendingWebhookEventDeleteResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Включается при ошибке. **/
    reason?: string
}

Структура SSO-пользователя

FastComments надає просте у використанні рішення SSO. Оновлення інформації користувача через інтеграцію на основі HMAC так само просте, як завантаження сторінки користувачем з оновленим payload.

Однак може бути бажаним керувати користувачем поза цим потоком, щоб підвищити узгодженість вашого застосунку.

SSO User API надає спосіб CRUD-операцій для об'єктів, які ми називаємо SSOUsers. Ці об'єкти відрізняються від звичайних Users і зберігаються окремо для типобезпеки.

Структура об'єкта SSOUser виглядає так:

Структура SSOUser

Copy

interface SSOUser {
    id: string
    username: string
    email?: string
    websiteUrl?: string
    signUpDate: number
    createdFromUrlId?: string
    loginCount?: number
    avatarSrc?: string
    optedInNotifications?: boolean
    optedInSubscriptionNotifications?: boolean
    displayLabel?: string
    displayName?: string
    isAccountOwner?: boolean // Разрешение адміністратора - SSO users з цим прапором враховуються як SSO Admins (окремо від звичайних SSO users)
    isAdminAdmin?: boolean // Разрешение адміністратора - SSO users з цим прапором враховуються як SSO Admins (окремо від звичайних SSO users)
    isCommentModeratorAdmin?: boolean // Разрешение модератора - SSO users з цим прапором враховуються як SSO Moderators (окремо від звичайних SSO users)
    /** Якщо null, Контроль доступу не буде застосований до користувача. Якщо порожній список, цей користувач не зможе бачити жодні сторінки або згадувати інших користувачів через @mention. **/
    groupIds?: string[] | null
    createdFromSimpleSSO?: boolean
    /** Не дозволяйте іншим користувачам бачити активність цього користувача, включаючи коментарі, на його профілі. За замовчуванням true, щоб забезпечити безпечні профілі за замовчуванням. **/
    isProfileActivityPrivate?: boolean
    /** Не дозволяйте іншим користувачам залишати коментарі в профілі користувача або бачити існуючі коментарі профілю. За замовчуванням false. **/
    isProfileCommentsPrivate?: boolean
    /** Не дозволяйте іншим користувачам надсилати цьому користувачу приватні повідомлення. За замовчуванням false. **/
    isProfileDMDisabled?: boolean
    karma?: number
    /** Необов'язкова конфігурація для бейджів користувача. **/
    badgeConfig?: {
        /** Масив ID бейджів, які призначаються користувачу. Обмежено 30 бейджами. Порядок зберігається. **/
        badgeIds: string[]
        /** Якщо true, замінює всі існуючі відображувані бейджі на вказані. Якщо false, додає до існуючих бейджів. **/
        override?: boolean
        /** Якщо true, оновлює властивості відображення бейджів з конфігурації tenant. **/
        update?: boolean
    }
}

Білінг для SSO користувачів

SSO users оплачуються по-різному в залежності від їхніх прапорів дозволів:

Регулярні SSO users: Користувачі без прав адміністратора або модератора оплачуються як регулярні SSO users
SSO Admins: Користувачі з прапорами isAccountOwner або isAdminAdmin оплачуються окремо як SSO Admins (така ж ставка, як для звичайних адміністраторів tenant)
SSO Moderators: Користувачі з прапором isCommentModeratorAdmin оплачуються окремо як SSO Moderators (така ж ставка, як для звичайних модераторів)

Важливо: Щоб запобігти подвійній оплаті, система автоматично дедуплікує SSO users щодо звичайних tenant users і moderators за адресою електронної пошти. Якщо SSO user має той самий адресу електронної пошти, що й звичайний tenant user або moderator, він не буде оплачений двічі.

Контроль доступу

Користувачів можна розбити на групи. Саме для цього призначено поле groupIds, і воно є необов'язковим.

@Упоминания

За замовчуванням @mentions будуть використовувати username для пошуку інших sso users, коли вводиться символ @. Якщо використовується displayName, то результати, що відповідають username, будуть ігноруватися, коли знайдено відповідність для displayName, і результати пошуку @mention будуть використовувати displayName.

Підписки

У FastComments користувачі можуть підписатися на сторінку, натиснувши іконку дзвінка у віджеті коментарів і вибравши Subscribe.

Для звичайного користувача ми відправляємо їм повідомлення електронною поштою відповідно до їхніх налаштувань повідомлень.

У випадку SSO Users ми розділяємо це для зворотної сумісності. Додаткові електронні листи з повідомленнями про підписки будуть надсилатися лише якщо ви встановите optedInSubscriptionNotifications в true.

Значки

Ви можете призначати значки SSO users за допомогою властивості badgeConfig. Значки — це візуальні індикатори, які відображаються поруч із ім'ям користувача в коментарях.

badgeIds - Масив ID бейджів, які призначаються користувачу. Ці ID повинні бути дійсними ID бейджів, створених у вашому акаунті FastComments. Обмежено 30 бейджами.
override - Якщо true, всі існуючі бейджі, що відображаються в коментарях, будуть замінені на вказані. Якщо false або опущено, вказані бейджі будуть додані до будь-яких існуючих бейджів.
update - Якщо true, властивості відображення бейджів будуть оновлюватися з конфігурації tenant щоразу, коли користувач входить в систему.

GET /api/v1/sso-users

Resource: SSOUser as GET /api/v1/sso-users Credit Cost: 10

Этот маршрут возвращает SSO-пользователей по страницам по 100. Пагинация обеспечивается параметром skip. Пользователи сортируются по полям signUpDate и id.

Приклад cURL для SSOUsers

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/sso-users?tenantId=demo&API_KEY=DEMO_API_SECRET'

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

Copy

interface SSOUsersRequestQueryParams {
    tenantId: string
    API_KEY: string
    skip?: number
}

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

Copy

interface SSOUsersResponse {
    status: 'success' | 'failed'
    /** Указывается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Указывается при ошибке. **/
    reason?: string
    users: SSOUser[]
}

GET /api/v1/sso-users/by-id/:id

Resource: SSOUser as GET /api/v1/sso-users/by-id/:id Credit Cost: 1

Этот маршрут возвращает одного SSO-пользователя по его id.

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

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/sso-users/by-id/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

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

Copy

interface SSOUserRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface SSOUserByIdResponse {
    status: 'success' | 'failed'
    /** Добавляется при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'user-does-not-exist'
    /** Добавляется при ошибке. **/
    reason?: string
    user: SSOUser
}

GET /api/v1/sso-users/by-email/:email

Resource: SSOUser as GET /api/v1/sso-users/by-email/:email Credit Cost: 1

Этот маршрут возвращает одного SSO-пользователя по адресу электронной почты.

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

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/sso-users/by-email/someone@somewhere.com?tenantId=demo&API_KEY=DEMO_API_SECRET'

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

Copy

interface SSOUserRequestByEmailQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface SSOUserByEmailResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-email' | 'user-does-not-exist'
    /** Включается при ошибке. **/
    reason?: string
    user: SSOUser
}

PATCH /api/v1/sso-users/:id

Resource: SSOUser as PATCH /api/v1/sso-users/:id Credit Cost: 1

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

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

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/sso-users/my-user-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "notfordperfect"
}'

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

Copy

interface SSOUserPatchQueryParams {
    tenantId: string
    API_KEY: string
    /** Если изменяется email или username, можно установить это в 'true', чтобы также обновить комментарии пользователя. Это удвоит стоимость в кредитах. **/
    updateComments: 'true' | 'false'
}

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

Copy

interface SSOUserPatchResponse {
    status: 'success' | 'failed'
    /** Указывается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-does-not-exist'
    /** Указывается при ошибке. **/
    reason?: string
    user?: SSOUser; // В случае успеха возвращаем полностью обновлённого пользователя.
}

POST /api/v1/sso-users

Resource: SSOUser as POST /api/v1/sso-users Credit Cost: 1

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

Попытка создать двух пользователей с одинаковым ID приведёт к ошибке.

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

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/sso-users?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "my-user-id",
    "username": "fordperfect",
    "displayName": "Ford Perfect",
    "email": "fordperfect@galaxy.com",
    "groupIds": ["some-optional-group-id"]
}'

В этом примере мы указываем groupIds для контроля доступа, но это необязательно.

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

Copy

interface SSOUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface SSOUserPostResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-exists'
    /** Включается при ошибке. **/
    reason?: string
    user?: SSOUser; // Мы возвращаем созданного пользователя в случае успеха.
}

Примечание по интеграции

Данные, переданные через API, можно переопределить, просто передав другой SSO User HMAC payload. Например, если вы задали username через API, но затем передаёте другой в SSO-потоке при загрузке страницы, мы автоматически обновим его username.

Мы не будем обновлять параметры пользователя в этом процессе, если вы явно не укажете их или не установите в null (не undefined).

PUT /api/v1/sso-users/:id

Resource: SSOUser as PUT /api/v1/sso-users Credit Cost: 1

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

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

Copy

curl --request PUT \
  --url 'https://fastcomments.com/api/v1/sso-users/my-user-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "fordperfect",
    "displayName": "Ford Perfect",
    "email": "fordperfect@galaxy.com",
    "groupIds": ["some-optional-group-id"]
}'

В этом примере мы указываем groupIds для контроля доступа, но это необязательно.

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

Copy

interface SSOUserPutQueryParams {
    tenantId: string
    API_KEY: string
    /** Если изменяется email или username, можно установить это в true, чтобы также обновить комментарии пользователя. Это удвоит стоимость в кредитах. **/
    updateComments: 'true' | 'false'
}

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

Copy

interface SSOUserPutResponse {
    status: 'success' | 'failed'
    /** Указывается в случае ошибки. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-exists'
    /** Указывается в случае ошибки. **/
    reason?: string
    user?: SSOUser; // Мы возвращаем обновлённого пользователя при успехе.
}

DELETE /api/v1/sso-users/:id

Resource: SSOUser as DELETE /api/v1/sso-users/:id Credit Cost: 1

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

Обратите внимание, что повторная загрузка виджета комментариев с payload для этого пользователя просто вновь создаст пользователя.

Удаление комментариев пользователя возможно через параметр запроса deleteComments. Обратите внимание, что если это правда:

Все комментарии пользователя будут удалены в реальном времени.
Все дочерние (теперь сиротские) комментарии будут удалены или анонимизированы в зависимости от конфигурации страницы, связанной с каждым комментарием. Например, если thread deletion mode равен "anonymize", то ответы останутся, а комментарии пользователя будут анонимизированы. Это применяется только когда commentDeleteMode установлен в Remove (значение по умолчанию).
creditsCost становится 2.

Анонимизированные комментарии

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

Если комментарии пользователя анонимизированы, то следующие значения устанавливаются в null:

- commenterName
- commenterEmail
- avatarSrc
- userId
- anonUserId
- mentions
- badges

isDeleted и isDeletedUser устанавливаются в true.

При рендеринге виджет комментариев будет использовать DELETED_USER_PLACEHOLDER (по умолчанию: "[deleted]") для имени пользователя и DELETED_CONTENT_PLACEHOLDER для комментария. Эти значения можно настроить через UI настройки виджета (Widget Customization UI).

Примеры

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

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/sso-users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

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

Copy

enum SSOUserCommentDeleteMode {
    Remove = 0, // по умолчанию
    Anonymize = 1
}
interface SSOUsersDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** Вы можете установить это в true, чтобы также удалить комментарии пользователя. Это удвоит стоимость в кредитах. **/
    deleteComments?: 'true' | 'false'
    /** Вы можете установить это по своему усмотрению, чтобы определить, как обрабатывать комментарии пользователя. **/
    commentDeleteMode?: SSOUserCommentDeleteMode
}

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

Copy

interface SSOUsersResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'user-does-not-exist'
    /** Включается при ошибке. **/
    reason?: string
    user?: SSOUser; // Мы возвращаем удаленного пользователя при успешном выполнении.
}

Структура подписки

Объект Subscription представляет подписку для пользователя.

Subscription объекты создаются, когда пользователь нажимает значок уведомлений в виджете комментариев и нажимает "Подписаться на эту страницу".

Подписки также можно создавать через API.

Наличие объекта Subscription вызывает создание объектов Notification и отправку электронных писем, когда на корне связанной страницы появляются новые комментарии, для которой предназначена подписка Subscription. Отправка писем зависит от типа пользователя. Для обычных пользователей это зависит от optedInNotifications. Для SSO-пользователей это зависит от optedInSubscriptionNotifications. Обратите внимание, что в некоторых приложениях может отсутствовать понятие веб-доступной страницы, в этом случае просто установите urlId равным идентификатору элемента, на который вы подписываетесь (то же значение для urlId, которое вы передали бы в виджет комментариев).

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

Структура Subscription

Copy

interface Subscription {
    id: string
    tenantId: string
    /** При SSO идентификатор пользователя имеет формат `<tenant id>:<user id>`. **/
    userId: string
    anonUserId?: string
    urlId: string
    url?: string
    pageTitle?: string
    createdAt: string // строка с датой
}

GET /api/v1/subscriptions/:id

Resource: Subscription as GET /api/v1/subscriptions Credit Cost: 1

Этот маршрут возвращает до 30 объектов Subscription, отсортированных по createdAt, самые новые первыми.

Вы можете фильтровать по userId. При SSO идентификатор пользователя имеет формат <tenant id>:<user id>.

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

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/subscriptions?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=SOME_USER_ID'

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

Copy

interface SubscriptionsGetQueryParams {
    tenantId: string
    API_KEY: string
    /** Пагинация через пропуск записей. **/
    skip?: number
    /** Фильтрация по пользователю. **/
    userId?: string
}

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

Copy

interface SubscriptionsGetResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Включается при ошибке. **/
    reason?: string
    subscriptions?: Subscription[]
}

POST /api/v1/subscriptions

Resource: Subscription as POST /api/v1/subscriptions Credit Cost: 1

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

Создание подписки приведёт к созданию объектов Notification, когда новый комментарий оставлен в корне подписанного urlId (когда parentId комментария равен null).

Пример cURL-запроса для Subscription (POST)

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/subscriptions?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "userId": "tenantId:test-user-id",
    "urlId": "some-page-id-or-url",
    "url": "https://example.com/page",
    "pageTitle": "Some Example Page!"
}'

Структура запроса Subscription POST

Copy

interface SubscriptionPostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура ответа Subscription POST

Copy

interface SubscriptionPostResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'unauthorized' | 'not-found';  
    /** Включается при ошибке. **/
    reason?: string
}

DELETE /api/v1/subscriptions/:id

Resource: Subscription as DELETE /api/v1/subscriptions Credit Cost: 1

Этот маршрут удаляет один объект Subscription по id.

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

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/subscriptions/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

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

Copy

interface SubscriptionsDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface SubscriptionDeleteResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Включается при ошибке. **/
    reason?: string
}

Структура ежедневного использования тенанта

Объект TenantDailyUsage представляет собой данные об использовании для тенанта за конкретный день. Если для данного тенанта в определённый день, у этого дня не будет объекта TenantDailyUsage.

Объект TenantDailyUsage не является данными в режиме реального времени и может отставать на несколько минут от фактического использования.

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

Структура TenantDailyUsage

Copy

export interface TenantDailyUsage {
    yearNumber: number
    monthNumber: number
    dayNumber: number
    commentFetchCount?: number
    commentCreateCount?: number
    conversationCreateCount?: number
    voteCount?: number
    accountCreatedCount?: number
    userMentionSearch?: number
    hashTagSearch?: number
    gifSearchTrending?: number
    gifSearch?: number
    apiCreditsUsed?: number
    createdAt: string
    billed: boolean
    /** Игнорируется при выставлении счетов. **/
    ignored: boolean
}

GET /api/v1/tenant-daily-usage

Resource: TenantDailyUsage as GET /api/v1/tenant-daily-usage Credit Cost: 1

Этот маршрут позволяет выполнять поиск использования арендатора по году, месяцу и дню. Может быть возвращено до 365 объектов, а стоимость составляет 1 API-кредит за каждые 10 объектов.

Объекты ответа сортируются по дате их создания (сначала самые старые).

Пример cURL запроса TenantDailyUsage

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenant-daily-usage?tenantId=demo&API_KEY=DEMO_API_SECRET&yearNumber=2022&monthNumber=2&dayNumber=10'

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

Copy

interface TenantDailyUsageQueryParams {
    tenantId: string
    API_KEY: string
    /** По UTC. **/
    yearNumber?: number
    /** Нумерация с нуля. По UTC. **/
    monthNumber?: number
    /** Нумерация с единицы. По UTC. **/
    dayNumber?: number
}

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

Copy

interface TenantDailyUsageResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Включается при ошибке. **/
    reason?: string
    tenantDailyUsages: TenantDailyUsage[]
}

Структура тенанта

Tenant определяет клиента FastComments.com. Их можно создать через API арендаторами с доступом white-label. Арендаторы с white-label не могут создавать других арендаторов с white-label (разрешён только один уровень вложенности).

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

Структура Tenant

Copy

export enum SiteType {
    Unknown = 0,
    WordPress = 1
}
/** Это также можно обработать через DomainConfig API. **/
export interface TenantDomainConfig {
    domain: string
    emailFromName?: string
    emailFromEmail?: string
    createdAt?: string,
    siteType?: FastCommentsSiteType, // вероятно, вы захотите Unknown
    logoSrc?: string, // путь к исходному изображению
    logoSrc100px?: string, // изменённый для миниатюр
    footerUnsubscribeURL?: string,
    emailHeaders?: Record<string, string>,
    disableUnsubscribeLinks?: boolean,
    dkim?: {
        domainName: string,
        keySelector: string,
        privateKey: string
    }
}
export interface TenantBillingInfo {
    name: string
    address: string
    city: string
    state: string
    zip: string
    country: string
}
export enum TenantPaymentFrequency {
    Monthly = 0,
    Annually = 1
}
export interface Tenant {
    id: string
    name: string
    email?: string
    signUpDate: number; // число по "legacy" причинам
    packageId?: string | null
    paymentFrequency?: TenantPaymentFrequency
    billingInfoValid?: boolean
    billingHandledExternally?: boolean
    createdBy?: string
    isSetup?: boolean
    domainConfiguration: FastCommentsAPITenantDomainConfig[]
    billingInfo?: FastCommentsAPITenantBillingInfo
    stripeCustomerId?: string
    stripeSubscriptionId?: string
    stripePlanId?: string
    enableProfanityFilter?: boolean
    enableSpamFilter?: boolean
    lastBillingIssueReminderDate?: string
    removeUnverifiedComments?: boolean
    unverifiedCommentsTTLms?: number
    commentsRequireApproval?: boolean
    autoApproveCommentOnVerification?: boolean
    sendProfaneToSpam?: boolean
    /** @readonly - Вычисляется на основе packageId. **/
    hasFlexPricing?: boolean
    /** @readonly **/
    flexLastBilledAmount?: number
    /** @readonly - Вычисляется на основе packageId. **/
    hasAuditing?: boolean
    /** Вы можете хранить пару ключ-значение у Tenant, которую можно использовать для запросов. Ключи не могут содержать "." или "$", или быть длиннее 100 символов. Значения не могут быть длиннее 2k символов. **/
    meta?: Record<string, string | null>
}

GET /api/v1/tenants/:id

Resource: Tenant as GET /api/v1/tenants/:id Credit Cost: 1

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

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

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenants/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

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

Copy

interface TenantByIdQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface TenantByIdResponse {
    status: 'success' | 'failed'
    /** Включается при неудаче. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'unauthorized'
    /** Включается при неудаче. **/
    reason?: string
    tenant?: Tenant
}

GET /api/v1/tenants

Resource: Tenant as GET /api/v1/tenants Credit Cost: 1

Этот API возвращает tenants, которыми управляет ваш tenant.

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

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

Пример cURL запроса Tenant

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenants?tenantId=demo&skip=0&API_KEY=DEMO_API_SECRET'

Вы можете задать параметры meta на объектах Tenant и выполнять запрос для поиска соответствующих tenants. Например, для ключа someKey и значения meta some-value мы можем сформировать JSON-объект с этой парой ключ/значение и затем URI-кодировать его как параметр запроса для фильтрации:

Пример cURL запроса Tenant по meta

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenants?tenantId=demo&skip=0&API_KEY=DEMO_API_SECRET&meta=%7B%22someKey%22%3A%22some-value%22%7D'

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

Copy

interface TenantsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** Количество tenants, которые нужно пропустить для пагинации. **/
    skip?: number
    /** Фильтр по meta-параметрам. **/
    meta?: string
}

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

Copy

interface TenantsResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Включается при ошибке. **/
    reason?: string
    tenants?: Tenant[]
}

POST /api/v1/tenants

Resource: Tenant as POST /api/v1/tenants Credit Cost: 1

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

При создании Tenant действуют следующие ограничения:

Поле name обязательно.
Поле domainConfiguration обязательно.
При создании Tenant нельзя указывать следующие значения:
- hasFlexPricing
- lastBillingIssueReminderDate
- flexLastBilledAmount
Значение signUpDate не может быть в будущем.
Длина name не может превышать 200 characters.
Длина email не может превышать 300 characters.
email должен быть уникален среди всех tenants FastComments.com.
Вы не можете создавать tenants, если у родительского tenant не определён действительный TenantPackage.
- Если ваш tenant был создан через FastComments.com, это не должно быть проблемой.
Вы не можете создать больше tenants, чем указано в maxWhiteLabeledTenants в вашем пакете.
Вы должны указать query-параметр tenantId, который является id вашего parent tenant с включенным white labeling.

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

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

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/tenants?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some Name",
    "email": "someone@someone.com",
    "domainConfiguration": [ { "domain": "somedomain.com" } ]
}'

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

Copy

interface TenantPostQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface TenantPostResponse {
    status: 'success' | 'failed'
    /** Указывается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' | 'unexpected-param' | 'sign-up-date-in-future' | 'payment-frequency-invalid' | 'cannot-change-payment-frequency' | 'name-invalid' | 'email-invalid' | 'email-taken' | 'no-package' | 'invalid-package' | 'unauthorized' | 'tenant-limit-reached' | 'cannot-move-tenant' | 'cannot-change-package' | 'invalid-billing-info'
    /** Указывается при ошибке. **/
    reason?: string
    tenant?: Tenant; // При успехе возвращается полностью созданный tenant.
}

PATCH /api/v1/tenants/:id

Resource: Tenant as PATCH /api/v1/tenants/:id Credit Cost: 1

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

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

Следующие значения нельзя обновлять:
- hasFlexPricing
- lastBillingIssueReminderDate
- flexLastBilledAmount
- managedByTenantId
signUpDate не может быть в будущем.
name не может быть длиннее 200 characters.
email не может быть длиннее 300 characters.
email должен быть уникальным среди всех тенантов FastComments.com.
При установке billingInfoValid в true, billingInfo должен быть предоставлен в том же запросе.
Вы не можете обновлять packageId, связанный с вашим собственным тенантом.
Вы не можете обновлять paymentFrequency, связанный с вашим собственным тенантом.

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

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/tenants/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some New Name",
}'

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

Copy

interface TenantPatchQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface TenantPatchResponse {
    status: 'success' | 'failed'
    /** Указывается при неудаче. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' | 'unexpected-param' | 'sign-up-date-in-future' | 'payment-frequency-invalid' | 'cannot-change-payment-frequency' | 'name-invalid' | 'email-invalid' | 'email-taken' | 'no-package' | 'invalid-package' | 'unauthorized' | 'tenant-limit-reached' | 'cannot-move-tenant' | 'cannot-change-package' | 'invalid-billing-info'; 
    /** Указывается при неудаче. **/
    reason?: string
}

DELETE /api/v1/tenants/:id

Resource: Tenant as DELETE /api/v1/tenants/:id Credit Cost: 1,000

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

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

tenant должен быть вашим собственным или white-labeled tenant, которым вы управляете.
Параметр запроса sure должен быть установлен в true.

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

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/tenants/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

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

Copy

interface TenantDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface TenantDeleteResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized' | 'unsure'
    /** Включается при ошибке. **/
    reason?: string
}

Структура пакета тенанта

Объект TenantPackage определяет информацию о пакете, доступном для Tenant. У Tenant может быть несколько доступных пакетов, но одновременно используется только один.

Tenant не может использоваться для каких-либо продуктов, пока его packageId не указывает на действительный TenantPackage.

Существует два типа объектов TenantPackage:

Пакеты с фиксированной ценой - где hasFlexPricing равно false.
Гибкая тарификация - где hasFlexPricing равно true.

В обоих случаях для аккаунта, использующего пакет, определяются ограничения, однако при Flex-ценообразовании тенант платит базовую цену плюс стоимость использованных ресурсов, определяемую параметрами flex*.

Тенант может иметь несколько пакетов и иметь возможность самостоятельно менять пакет со страницы Страница платёжной информации.

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

Нельзя создавать пакеты с лимитами выше, чем у родительского Tenant.

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

Структура TenantPackage

Copy

export interface TenantPackage {
    id: string
    name: string
    tenantId: string
    createdAt: string
    monthlyCostUSD: number
    yearlyCostUSD: number
    monthlyStripePlanId?: string
    yearlyStripePlanId?: string
    maxMonthlyPageLoads: number
    maxMonthlyAPICredits: number
    maxMonthlyComments: number
    maxConcurrentUsers: number
    maxTenantUsers: number
    maxSSOUsers: number
    maxModerators: number
    maxDomains: number
    maxWhiteLabeledTenants: number
    hasWhiteLabeling: boolean
    hasDebranding: boolean
    forWhoText: string
    featureTaglines: string[]
    hasAuditing: boolean
    hasFlexPricing: boolean
    flexPageLoadCostCents?: null
    flexPageLoadUnit?: null
    flexCommentCostCents?: null
    flexCommentUnit?: null
    flexSSOUserCostCents?: null // Стоимость за обычного SSO-пользователя (без прав администратора/модератора)
    flexSSOUserUnit?: null
    flexAPICreditCostCents?: null
    flexAPICreditUnit?: null
    flexModeratorCostCents?: null
    flexModeratorUnit?: null
    flexAdminCostCents?: null
    flexAdminUnit?: null
    flexDomainCostCents?: null
    flexDomainUnit?: null
    flexSSOAdminCostCents?: null // Стоимость за SSO-пользователя с правами администратора (флаги isAccountOwner или isAdminAdmin)
    flexSSOAdminUnit?: null
    flexSSOModeratorCostCents?: null // Стоимость за SSO-пользователя с правами модератора (флаг isCommentModeratorAdmin)
    flexSSOModeratorUnit?: null
    flexMinimumCostCents?: null
}

GET /api/v1/tenant-packages/:id

Resource: TenantPackage as GET /api/v1/tenant-packages/:id Credit Cost: 1

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

Пример cURL запроса TenantPackage по id

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenant-packages/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

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

Copy

interface TenantPackageByIdQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface TenantPackageByIdResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Включается при ошибке. **/
    reason?: string
    tenantPackage: TenantPackage
}

GET /api/v1/tenant-packages

Resource: TenantPackage as GET /api/v1/tenant-packages Credit Cost: 1

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

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

Пример cURL запроса TenantPackage

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenant-packages?tenantId=demo&skip=0&API_KEY=DEMO_API_SECRET'

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

Copy

interface TenantPackagesRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** Количество TenantPackages, которые нужно пропустить для пагинации. **/
    skip?: number
}

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

Copy

interface TenantPackagesResponse {
    status: 'success' | 'failed'
    /** Указывается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Указывается при ошибке. **/
    reason?: string
    tenantPackages?: TenantPackage[]
}

POST /api/v1/tenant-packages

Resource: TenantPackage as POST /api/v1/tenant-packages Credit Cost: 1

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

При создании TenantPackage действуют следующие ограничения:

Требуются следующие параметры:
- name
- tenantId
- monthlyCostUSD - Может быть null.
- yearlyCostUSD - Может быть null.
- maxMonthlyPageLoads
- maxMonthlyAPICredits
- maxMonthlyComments
- maxConcurrentUsers
- maxTenantUsers
- maxSSOUsers
- maxModerators
- maxDomains
- hasDebranding
- forWhoText
- featureTaglines
- hasFlexPricing - Если true, то все параметры flex* обязательны.
name не может превышать 50 characters.
Каждый элемент forWhoText не может быть длиннее 200 characters.
Каждый элемент featureTaglines не может быть длиннее 100 characters.
TenantPackage должен быть «меньше» родительского tenant. Например, все параметры max* должны иметь значения меньше, чем у родительского tenant.
У white labeled tenant может быть максимум пять пакетов.
Только tenants с доступом white labeling могут создать TenantPackage.
Вы не можете добавлять пакеты в свой собственный tenant. :)

Мы можем создать TenantPackage следующим образом:

Пример cURL-запроса создания TenantPackage через Email

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/tenant-packages?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Default Package",
  "tenantId": "some-child-tenant-id",
  "monthlyCostUSD": null,
  "yearlyCostUSD": null,
  "maxMonthlyPageLoads": 50000,
  "maxMonthlyAPICredits": 50000,
  "maxMonthlyComments": 50000,
  "maxConcurrentUsers": 50000,
  "maxTenantUsers": 10,
  "maxSSOUsers": 50000,
  "maxModerators": 100,
  "maxDomains": 3,
  "hasWhiteLabeling": false,
  "hasDebranding": true,
  "forWhoText": "For Everyone",
  "featureTaglines": [
    "Some Tag",
    "Some Other Tag"
  ],
  "hasFlexPricing": true,
  "flexPageLoadCostCents": 100,
  "flexPageLoadUnit": 100000,
  "flexCommentCostCents": 100,
  "flexCommentUnit": 100000,
  "flexSSOUserCostCents": 100,
  "flexSSOUserUnit": 1000,
  "flexAPICreditCostCents": 100,
  "flexAPICreditUnit": 50000,
  "flexModeratorCostCents": 500,
  "flexModeratorUnit": 1,
  "flexAdminCostCents": 1000,
  "flexAdminUnit": 1,
  "flexDomainCostCents": 1000,
  "flexDomainUnit": 1,
  "flexMinimumCostCents": 99
}'

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

Copy

interface TenantPackagePostQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface TenantPackagePostResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' 'white-labeling-not-allowed' | 'name-too-long' | 'for-who-text-too-long' | 'feature-tag-lines-too-long' | 'no-package' | 'invalid-package' | 'unauthorized' | 'child-tenant-too-large' | 'flex-param-missing' | 'unexpected-flex-param' | 'package-limit-reached' | 'flex-param-missing' | 'unexpected-flex-param'
    /** Включается при ошибке. **/
    reason?: string
    tenantPackage?: TenantPackage; // При успехе возвращаем полностью созданный TenantPackage.
}

PATCH /api/v1/tenant-packages/:id

Resource: TenantPackage as PATCH /api/v1/tenant-packages/:id Credit Cost: 1

Эта конечная точка API предоставляет возможность обновить TenantPackage по id.

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

Если вы устанавливаете hasFlexPricing в true, то все параметры flex* обязательны в том же запросе.
Значение name не может быть длиннее, чем 50 characters.
Каждый элемент forWhoText не может быть длиннее, чем 200 characters.
Каждый элемент featureTaglines не может быть длиннее, чем 100 characters.
TenantPackage должен быть "меньше", чем родительский tenant. Например, все параметры max* должны иметь значения меньше, чем у родительского tenant.
Вы не можете изменить tenantId, связанный с TenantPackage.

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

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/tenant-packages/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some New Name",
}'

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

Copy

interface TenantPackagePatchQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface TenantPackagePatchResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' | 'white-labeling-not-allowed' | 'name-too-long' | 'for-who-text-too-long' | 'feature-tag-lines-too-long' | 'no-package' | 'invalid-package' | 'unauthorized' | 'child-tenant-too-large' | 'flex-param-missing' | 'unexpected-flex-param' | 'package-limit-reached' | 'flex-param-missing' | 'unexpected-flex-param'; 
    /** Включается при ошибке. **/
    reason?: string
}

DELETE /api/v1/tenant-packages/:id

Resource: TenantPackage as DELETE /api/v1/tenant-packages/:id Credit Cost: 5

Этот маршрут предоставляет удаление TenantPackage по id.

Вы не можете удалить TenantPackage, который используется (у tenant поле packageId указывает на этот пакет). Сначала обновите Tenant.

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

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/tenant-packages/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

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

Copy

interface TenantPackageDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface TenantPackageDeleteResponse {
    status: 'success' | 'failed'
    /** Включается в случае ошибки. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized' | 'package-in-use'
    /** Включается в случае ошибки. **/
    reason?: string
}

Структура пользователя тенанта

TenantUser определяет User, которым управляет конкретный tenant. Их аккаунт полностью контролируется tenant'ом, с которым они связаны, и его можно обновлять или удалять через UI или API.

Пользователи tenant могут быть администраторами со всеми правами и доступом к Tenant, или их доступ может быть ограничен определёнными разрешениями для модерации комментариев, доступа к API-ключам и т.д.

The structure for the TenantUser object is as follows:

Структура TenantUser

Copy

/** Это для уведомлений. **/
export enum UserDigestEmailFrequency {
    Disabled = -1,
    Daily = 0,
    Weekly = 1,
    Monthly = 2
}
export interface TenantUser {
    id: string
    tenantId: string
    username: string
    /** Ссылка, например, на блог комментатора. **/
    websiteUrl?: string
    email: string
    signUpDate: number
    createdFromUrlId: string
    createdFromTenantId: string
    verified: boolean
    loginCount: number
    optedInNotifications: boolean
    optedInTenantNotifications: boolean
    hideAccountCode: boolean
    avatarSrc?: string
    /** Получает ли пользователь запросы о помощи от комментаторов? **/
    isHelpRequestAdmin: boolean
    isAccountOwner: boolean
    isAdminAdmin: boolean
    isBillingAdmin: boolean
    isAnalyticsAdmin: boolean
    isCustomizationAdmin: boolean
    isManageDataAdmin: boolean
    isCommentModeratorAdmin: boolean
    isAPIAdmin: boolean
    moderatorIds: string[]
    locale: FastCommentsLocale
    digestEmailFrequency: UserDigestEmailFrequency
    lastLoginDate: string
    displayLabel?: string
    karma?: number
}

GET /api/v1/tenant-users/:id

Resource: TenantUser as GET /api/v1/tenant-users/:id Credit Cost: 1

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

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

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenant-users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

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

Copy

interface TenantUserByIdQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface TenantUserByIdResponse {
    status: 'success' | 'failed'
    /** Указывается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'unauthorized'
    /** Указывается при ошибке. **/
    reason?: string
    tenantUser?: TenantUser
}

GET /api/v1/tenant-users

Resource: TenantUser as GET /api/v1/tenant-users Credit Cost: 1

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

Стоимость основывается на количестве возвращённых TenantUsers — 1 кредит за 10 возвращённых пользователей.

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

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenant-users?tenantId=demo&page=0&API_KEY=DEMO_API_SECRET'

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

Copy

interface TenantUsersRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** Количество пользователей арендатора, которые нужно пропустить для пагинации. **/
    skip?: number
}

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

Copy

interface TenantUsersResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Включается при ошибке. **/
    reason?: string
    tenantUsers?: TenantUser[]
}

POST /api/v1/tenant-users

Resource: TenantUser as POST /api/v1/tenant-users Credit Cost: 1

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

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

username обязателен.
email обязателен.
signUpDate не может быть в будущем.
locale должен быть в списке Supported Locales.
username должен быть уникальным на FastComments.com. Если это проблема, мы рекомендуем использовать SSO.
email должен быть уникальным на FastComments.com. Если это проблема, мы рекомендуем использовать SSO.
Вы не можете создать больше tenant users, чем определено в maxTenantUsers в вашем пакете.

Мы можем создать TenantUser следующим образом

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

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/tenants?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "Some Name",
    "email": "someone@someone.com"
}'

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

Copy

interface TenantUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface TenantUserPostResponse {
    status: 'success' | 'failed'
    /** Включается в случае ошибки. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'username-required' | 'email-required' | 'sign-up-date-in-future' | 'unsupported-locale' | 'unauthorized' | 'username-taken' | 'email-taken' | 'tenant-user-limit-reached'
    /** Включается в случае ошибки. **/
    reason?: string
    tenantUser?: TenantUser; // При успехе возвращается полностью созданный TenantUser.
}

Resource: TenantUser as POST /api/v1/tenant-users/:id/send-login-link Credit Cost: 10

Этот маршрут позволяет отправить ссылку для входа одному TenantUser.

Полезно при массовом создании пользователей, чтобы не объяснять им, как войти на FastComments.com. Это просто отправит им «магическую ссылку» для входа, срок действия которой истекает через 30 days.

Существуют следующие ограничения для отправки ссылки входа TenantUser:

TenantUser должен уже существовать.
У вас должен быть доступ к управлению Tenant, которому принадлежит TenantUser.

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

Пример cURL-запроса ссылки входа TenantUser

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/tenant-users/xyz/send-login-link?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json'

This will send an email like Bob at TenantName is inviting you to be a moderator...

Структура запроса ссылки входа TenantUser

Copy

interface TenantUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура ответа ссылки входа TenantUser

Copy

interface TenantUserPostResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'not-found'
    /** Включается при ошибке. **/
    reason?: string
}

PATCH /api/v1/tenant-users/:id

Resource: TenantUser as PATCH /api/v1/tenant-users/:id Credit Cost: 1

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

При обновлении TenantUser действуют следующие ограничения:

Значение signUpDate не может быть в будущем.
Значение locale должен быть в списке Supported Locales.
Значение username должно быть уникальным для всего FastComments.com. Если это проблема, мы рекомендуем использовать SSO.
Значение email должно быть уникальным для всего FastComments.com. Если это проблема, мы рекомендуем использовать SSO.
Вы не можете обновлять tenantId пользователя.

Мы можем создать TenantUser следующим образом

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

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/tenant-users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "Some Name",
    "email": "someone@someone.com"
}'

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

Copy

interface TenantUserPatchQueryParams {
    tenantId: string
    API_KEY: string
    /** Если изменяется email или username, вы можете установить это в true, чтобы также обновить комментарии пользователя. Это удвоит стоимость в кредитах. **/
    updateComments: 'true' | 'false'
}

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

Copy

interface TenantUserPatchResponse {
    status: 'success' | 'failed'
    /** Присутствует при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'sign-up-date-in-future' | 'unsupported-locale' | 'unauthorized' | 'username-taken' | 'email-taken' | 'unauthorized' | 'no-package' | 'invalid-package' | 'tenant-user-limit-reached' | 'user-does-not-exist'
    /** Присутствует при ошибке. **/
    reason?: string
}

DELETE /api/v1/tenant-users/:id

Resource: TenantUser as DELETE /api/v1/tenant-users/:id Credit Cost: 5

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

Удаление комментариев пользователя возможно через параметр запроса deleteComments. Обратите внимание, что если он равен true:

Все комментарии пользователя будут удалены в реальном времени.
Все child (теперь сиротские) комментарии будут удалены или анонимизированы в зависимости от конфигурации страницы, связанной с каждым комментарием. Например, если режим удаления ветки — "anonymize", то ответы останутся, а комментарии пользователя будут анонимизированы. Это применяется только когда commentDeleteMode равен Remove (значение по умолчанию).
Значение creditsCost становится равным 2.

Анонимизированные комментарии

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

Если комментарии пользователя анонимизированы, то следующие значения устанавливаются в null:

- commenterName
- commenterEmail
- avatarSrc
- userId
- anonUserId
- mentions
- badges

Поля isDeleted и isDeletedUser устанавливаются в true.

При отрисовке виджет комментариев будет использовать DELETED_USER_PLACEHOLDER (по умолчанию: "[deleted]") в качестве имени пользователя и DELETED_CONTENT_PLACEHOLDER для содержимого комментария. Это можно настроить через интерфейс настройки виджета.

Примеры

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

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/tenant-users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

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

Copy

enum TenantUserCommentDeleteMode {
    Remove = 0, // по умолчанию
    Anonymize = 1
}
interface TenantUserDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** Вы можете установить это в true, чтобы также удалить комментарии пользователя. Это удвоит стоимость в кредитах. **/
    deleteComments?: 'true' | 'false'
    /** Вы можете задать это, чтобы определить, как обрабатывать комментарии пользователя. **/
    commentDeleteMode?: TenantUserCommentDeleteMode
}

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

Copy

interface TenantUserDeleteResponse {
    status: 'success' | 'failed'
    /** Включается в случае ошибки. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized'
    /** Включается в случае ошибки. **/
    reason?: string
}

Структура пользователя

User — это объект, который представляет собой наибольший общий знаменатель всех пользователей.

Имейте в виду, что в FastComments у нас есть несколько разных сценариев использования пользователей:

Secure SSO
Simple SSO
Tenant Users (For example: Administrators)
Commenters

Этот API предназначен для Комментаторов и пользователей, созданных через Simple SSO. По сути, любой пользователь, созданный через ваш сайт, доступен через этот API. Пользователи арендатора также могут быть получены таким образом, но вы получите больше информации, взаимодействуя с API /tenant-users/.

Для Secure SSO используйте API /sso-users/.

Вы не можете обновлять эти типы пользователей. Они создали свои аккаунты через ваш сайт, поэтому мы предоставляем лишь базовый доступ только для чтения, но вы не можете вносить изменения. Если вы хотите иметь такой поток — вам нужно настроить Secure SSO.

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

Структура User

Copy

export interface User {
    /** Это также id, используемый как userId в объектах комментариев. **/
    id: string
    username: string
    /** Ссылка, например, на блог комментатора. **/
    websiteUrl?: string
    email: string
    signUpDate: number
    createdFromUrlId: string
    createdFromTenantId: string
    avatarSrc?: string
    locale: FastCommentsLocale
    displayLabel?: string
    karma?: number
}

GET /api/v1/users/:id

Resource: User as GET /api/v1/users/:id Credit Cost: 1

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

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

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

Структура запроса пользователя

Copy

interface UserByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Структура ответа пользователя

Copy

interface UserByIdResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'unauthorized'
    /** Включается при ошибке. **/
    reason?: string
    user?: User
}

Структура голоса

Объект Vote представляет голос, оставленный пользователем.

Связь между комментариями и голосом определяется через commentId.

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

Структура Vote

Copy

interface Vote {
    id: string
    urlId: string
    commentId: string
    userId: string
    direction: 1 | -1
    createdAt: string
}

GET /api/v1/votes

Resource: Vote as GET /api/v1/votes Credit Cost: 10

Голоса необходимо получать по urlId.

Типы голосов

Существует три типа голосов:

Авторизованные голоса, которые применяются к соответствующему комментарию. Вы можете создавать их через этот API.
Авторизованные голоса, которые находятся в процессе верификации, и поэтому ещё не применены к комментарию. Они создаются, когда пользователь использует механизм FastComments.com вход для голосования.
Анонимные голоса, которые применяются к соответствующему комментарию. Они создаются вместе с анонимными комментариями.

Они возвращаются в отдельных списках в API, чтобы уменьшить путаницу.

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

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/votes?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=test'

Структура запроса голосов

Copy

interface VotesRequestQueryParams {
    tenantId: string
    API_KEY: string
    urlId: string
}

Структура ответа голосов

Copy

interface VotesResponse {
    status: 'success' | 'failed'
    /** Включено при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id'
    /** Включено при ошибке. **/
    reason?: string
    /** Авторизованные, проверенные голоса, применённые к соответствующим комментариям. **/
    appliedAuthorizedVotes: Vote[]
    /** Анонимные голоса, применённые к соответствующим комментариям. **/
    appliedAnonymousVotes: Vote[]
    /** Голоса, ожидающие верификации, ещё не применённые к соответствующим комментариям. **/
    pendingVotes: Vote[]
}

Примечания по анонимным голосам

Обратите внимание, что анонимные голоса, созданные через этот API, появятся в списке appliedAuthorizedVotes. Они считаются авторизованными, так как были созданы через API с использованием API-ключа.

Структура appliedAnonymousVotes предназначена для голосов, созданных без электронной почты, API-ключа и т.д.

GET /api/v1/votes/for-user

Resource: Vote as GET /api/v1/votes/for-user Credit Cost: 1

Позволяет получить голоса, оставленные пользователем для заданного urlId. Принимает userId, который может быть любым пользователем FastComments.com или SSO User.

Это полезно, если вы хотите показать, голосовал ли пользователь за комментарий. При получении комментариев просто вызовите этот API одновременно для пользователя с тем же urlId.

Если вы используете анонимное голосование, то вместо этого передайте anonUserId.

Пример cURL-запроса — Голоса для пользователя

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/votes/for-user?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=test&userId=some-user-id'

Пример cURL-запроса — Голоса для анонимного пользователя

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/votes/for-user?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=test&anonUserId=some-user-id'

Обратите внимание, что анонимные голоса появятся в списке appliedAuthorizedVotes. Они считаются авторизованными, поскольку были созданы через API с использованием API-ключа.

Структура запроса — Голоса для пользователя

Copy

interface VotesForUserRequestQueryParams {
    tenantId: string
    API_KEY: string
    urlId: string
    userId?: string
    anonUserId?: string
}

Структура ответа — Голоса для пользователя

Copy

interface VotesForUserResponse {
    status: 'success' | 'failed'
    /** Указывается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'invalid-user-id'
    /** Указывается при ошибке. **/
    reason?: string
    /** Авторизованные, проверенные голоса, применённые к соответствующим комментариям. **/
    appliedAuthorizedVotes: Vote[]
    /** Голоса, ожидающие проверки, ещё не применённые к соответствующим комментариям. **/
    pendingVotes: Vote[]
}

POST /api/v1/votes

Resource: Vote as POST /api/v1/votes Credit Cost: 1

Этот маршрут предоставляет возможность добавить один авторизованный Vote. Голос может быть up (+1) или down (-1).

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

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/votes?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=user-id&commentId=comment-id&direction=up' \
  --header 'Content-Type: application/json'

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

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/votes?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-randomly-generated-identifier&commentId=comment-id&direction=up' \
  --header 'Content-Type: application/json'

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

Copy

interface VotePostQueryParams {
    tenantId: string
    API_KEY: string
    userId?: string
    anonUserId?: string
    commentId: string
    direction: 'up' | 'down'
}

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

Copy

interface VotePostResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-user-id' | 'invalid-user-id' | 'invalid-comment-id' | 'invalid-direction' | 'duplicate' | 'voting-disabled'
    /** Включается при ошибке. **/
    reason?: string
    voteId?: string
}

Создание анонимных голосов

Анонимные голоса можно создать, передав anonUserId в параметрах запроса вместо userId.

Этот идентификатор не обязательно должен соответствовать объекту пользователя где-либо (отсюда — анонимность). Это просто идентификатор сессии, чтобы вы могли повторно получить голоса в той же сессии и проверить, был ли за комментарий отдан голос.

Если у вас нет «анонимных сессий», как у FastComments, вы можете просто присвоить этому значение случайного идентификатора, например UUID (хотя мы предпочитаем более короткие идентификаторы для экономии места).

Прочие заметки

Этот API следует настройкам на уровне тенанта. Например, если вы отключите голосование для данной страницы и попытаетесь создать голос через API, это завершится с ошибкой с кодом voting-disabled.
Этот API активен по умолчанию.
Этот API обновит votes соответствующего Comment.

DELETE /api/v1/votes/:id

Resource: Vote as DELETE /api/v1/votes/:id Credit Cost: 1

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

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

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/votes/some-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json'

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

Copy

interface VoteDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface VoteDeleteResponse {
    status: 'success' | 'failed'
    /** Присутствует в случае ошибки. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id'
    /** Присутствует в случае ошибки. **/
    reason?: string
}

Примечания:

Этот API подчиняется настройкам на уровне тенанта. Например, если вы отключите голосование для определённой страницы, и попытаетесь создать голос через API, это завершится ошибкой с кодом voting-disabled.
Этот API по умолчанию действует в реальном окружении.
Этот API обновит votes соответствующего Comment.

Структура конфигурации домена

A DomainConfig object представляет конфигурацию для домена для арендатора.

The structure for the DomainConfig object is as follows:

Структура DomainConfig

Copy

interface DomainConfig {
    /** Домен, а не URL, например "fastcomments.com" или "www.example.com". Можно включить поддомен, если нужно ограничить до поддомена. Максимум 1000 символов. **/
    domain: string
    /** Имя отправителя (From-Name), используемое при отправке писем. **/
    emailFromName?: string
    /** Адрес отправителя (From-Email), используемый при отправке писем. Убедитесь, что SPF настроен так, чтобы mail.fastcomments.com мог отправлять письма от имени домена, указанный в этом атрибуте. **/
    emailFromEmail?: string
    /** ТОЛЬКО ДЛЯ ЧТЕНИЯ. Когда объект был создан. **/
    createdAt: string
    /** Логотип, связанный с этим доменом. Используется в письмах. Используйте HTTPS. **/
    logoSrc?: string
    /** Меньший логотип, связанный с этим доменом. Используйте HTTPS. **/
    logoSrc100px?: string
    /** ТОЛЬКО ДЛЯ SSO. URL, используемый в футере каждого отправляемого письма. Поддерживает переменную "[userId]". **/
    footerUnsubscribeURL?: string
    /** ТОЛЬКО ДЛЯ SSO. Заголовки, используемые в каждом отправляемом письме. Полезно, например, для установки заголовков, связанных с отпиской, чтобы улучшить доставляемость. Запись List-Unsubscribe в этом Record, если она существует, поддерживает переменную "[userId]". **/
    emailHeaders?: Record<string, string>
    /** Отключить все ссылки для отписки. Не рекомендуется, может ухудшить показатели доставляемости. **/
    disableUnsubscribeLinks?: boolean
    /** Конфигурация DKIM. **/
    dkim?: DomainConfigDKIM
}

Структура конфигурации DKIM

Copy

interface DomainConfigDKIM {
    /** Имя домена в вашей DKIM-записи. **/
    domainName: string
    /** Селектор ключа DKIM, который нужно использовать. **/
    keySelector: string
    /** Ваш приватный ключ. Начинается с -----BEGIN PRIVATE KEY----- и заканчивается -----END PRIVATE KEY----- **/
    privateKey: string
}

Для аутентификации

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

Не удаляйте и не изменяйте свойство domain у Domain Config для домена, который в настоящее время используется, если только вы не намерены отключить этот домен.

Это имеет тот же эффект, что и удаление домена через /auth/my-account/configure-domains.

Также обратите внимание, что удаление домена из интерфейса My Domains удалит любую соответствующую конфигурацию для этого домена, которая могла быть добавлена через этот интерфейс.

Для настройки писем

Ссылку для отписки в футере письма и функцию отписки в один клик, предлагаемую многими почтовыми клиентами, можно настроить через этот API, задав соответственно footerUnsubscribeURL и emailHeaders.

Для DKIM

После определения DKIM записей DNS просто обновите DomainConfig своей конфигурацией DKIM, используя определённую структуру.

GET /api/v1/domain-configs

Resource: Comment as GET /api/v1/domain-configs Credit Cost: 1

Этот API предоставляет возможность получить все объекты DomainConfig для тенанта.

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

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/domain-configs?tenantId=demo&API_KEY=DEMO_API_SECRET'

Структура запроса DomainConfig GET

Copy

interface GetDomainConfigsRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Структура ответа DomainConfig GET

Copy

interface GetDomainConfigsResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Включается при ошибке. **/
    reason?: string
    /** Конфигурации! **/
    configurations: DomainConfig[] | null
}

GET /api/v1/domain-configs/:domain

Resource: DomainConfig as GET /api/v1/domain-configs/:domain Credit Cost: 1

Отдельные DomainConfigs можно получить по соответствующему domain.

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

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/domain-configs/example.com?tenantId=demo&API_KEY=DEMO_API_SECRET'

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

Copy

interface DomainConfigsByDomainRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Структура ответа для получения конфигурации домена по домену

Copy

interface DomainConfigResponse {
    status: 'success' | 'failed'
    /** Включено при ошибке. **/
    code?: 'internal' | 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'missing-domain' | 'update-would-create-duplicate' | 'domain-does-not-exist'
    /** Включено при ошибке. **/
    reason?: string
    configuration?: DomainConfig | null
}

POST /api/v1/domain-configs

Resource: DomainConfig as POST /api/v1/domain-configs Credit Cost: 1

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

Добавление конфигурации для домена авторизует этот домен для аккаунта FastComments.

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

Пример cURL запроса DomainConfig POST

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/domain-configs?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "domain": "example.com",
    "emailFromName": "some from name",
    "emailFromEmail": "some@test.com",
    "logoSrc": "https://example.com/my-logo-big.png",
    "logoSrc100px": "https://example.com/my-logo-100px.png",
    "footerUnsubscribeURL": "http://example.com/unsubscribe-ui",
    "emailHeaders": {
        "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
        "List-Unsubscribe": "<https://example.com/opt-out/[userId]>"
    }
}'

Структура запроса DomainConfig POST

Copy

interface DomainConfigPostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура ответа DomainConfig POST

Copy

interface DomainConfigPostResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'missing-domain' | 'configuration-exists-for-domain' | 'domain-too-long' | 'domain-invalid';  
    /** Включается при ошибке. **/
    reason?: string
    /** Созданная конфигурация. **/
    configuration?: DomainConfig
}

PATCH /api/v1/domain-configs/:domain

Resource: DomainConfig as PATCH /api/v1/domain-configs/:domain Credit Cost: 1

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

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

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/domain-configs/example.com?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "emailFromName": "Some New From Name",
}'

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

Copy

interface DomainConfigPatchQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface DomainConfigPatchResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'missing-domain' | 'domain-does-not-exist' | 'update-would-create-duplicate' | 'domain-too-long' | 'domain-invalid';  
    /** Включается при ошибке. **/
    reason?: string
    /** Обновлённая конфигурация. **/
    configuration?: DomainConfig
}

PUT /api/v1/domain-configs/:domain

Resource: DomainConfig as PUT /api/v1/domain-configs/:domain Credit Cost: 1

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

Пример cURL для DomainConfig PUT

Copy

curl --request PUT \
  --url 'https://fastcomments.com/api/v1/domain-configs/example.com?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "domain": "new-domain-example.com",
    "emailFromName": "some from name",
    "emailFromEmail": "some@test.com",
    "logoSrc": "https://example.com/my-logo-big.png",
    "logoSrc100px": "https://example.com/my-logo-100px.png",
    "footerUnsubscribeURL": "http://example.com/unsubscribe-ui",
    "emailHeaders": {
        "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
        "List-Unsubscribe": "<https://example.com/opt-out/[userId]>"
    }
}'

Структура запроса DomainConfig PUT

Copy

interface DomainConfigPutQueryParams {
    tenantId: string
    API_KEY: string
}

Структура ответа DomainConfig PUT

Copy

interface DomainConfigPutResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'missing-domain' | 'domain-does-not-exist' | 'update-would-create-duplicate' | 'domain-too-long' | 'domain-invalid';  
    /** Включается при ошибке. **/
    reason?: string
    /** Обновлённая конфигурация. **/
    configuration?: DomainConfig
}

DELETE /api/v1/domain-configs/:domain

Resource: DomainConfig as DELETE /api/v1/domain-configs/:domain Credit Cost: 1

Этот маршрут удаляет один DomainConfig по идентификатору.

Примечание: Удаление DomainConfig лишит этот домен авторизации на использование FastComments.
Примечание: Повторное добавление домена через UI воссоздаст объект (с заполненным только полем domain).

Пример cURL для удаления DomainConfig

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/domain-configs/example.com?tenantId=demo&API_KEY=DEMO_API_SECRET'

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

Copy

interface DomainConfigRequestQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface DomainConfigDeleteResponse {
    status: 'success' | 'failed'
    /** Указывается при неудаче. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-domain' | 'domain-config-does-not-exist'
    /** Указывается при неудаче. **/
    reason?: string
}

Структура конфигурации вопроса

FastComments предоставляет способ создания вопросов и агрегирования их результатов. Пример вопроса (в дальнейшем называемого QuestionConfig) может быть рейтингом в виде звёзд, ползунком или вопросом NPS (определяется через type).

Данные вопросов можно агрегировать отдельно, вместе, по времени, в целом, по странице и т.д.

Фреймворк обладает всеми возможностями, необходимыми для создания клиентских виджетов (с вашим сервером перед этим API), административных панелей и инструментов отчётности.

Сначала нам нужно определить QuestionConfig. Структура выглядит следующим образом:

Структура QuestionConfig

Copy

type QuestionConfigType = 'nps' | 'slider' | 'star' | 'thumbs';
interface QuestionConfig {
    id: string
    tenantId: string
    name: string
    question: string
    helpText?: string
    createdAt: string
    createdBy: string
    /** ТОЛЬКО ДЛЯ ЧТЕНИЯ - увеличивается при каждом новом ответе. **/
    usedCount: number
    /** Строка с датой, когда конфигурация была в последний раз использована (оставлен результат). **/
    lastUsed?: string
    type: QuestionConfigType
    numStars?: number
    min?: number
    max?: number
    defaultValue?: number
    labelNegative?: string
    labelPositive?: string
    subQuestionIds?: string[]
    alwaysShowSubQuestions?: boolean
    reportingOrder: number
}

GET /api/v1/question-configs

Resource: QuestionConfig as GET /api/v1/question-configs Credit Cost: 1

Этот маршрут возвращает до 100 QuestionConfig объектов за раз, с пагинацией. Стоимость — 1 за каждые 100 объектов. Они отсортированы по тексту вопроса по возрастанию (question field).

Пример QuestionConfig

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/question-configs?tenantId=demo&API_KEY=DEMO_API_SECRET'

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

Copy

interface QuestionConfigRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
    /** Для пагинации. Начинается с 0. **/
    skip?: number
}

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

Copy

interface QuestionConfigByIdResponse {
    status: 'success' | 'failed'
    /** Указывается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Указывается при ошибке. **/
    reason?: string
    questionConfigs: QuestionConfig[]
}

GET /api/v1/question-configs/:id

Resource: QuestionConfig as GET /api/v1/question-configs/:id Credit Cost: 1

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

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

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/question-configs/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

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

Copy

interface QuestionConfigRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface QuestionConfigByIdResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Включается при ошибке. **/
    reason?: string
    questionConfig?: QuestionConfig
}

POST /api/v1/question-configs

Resource: QuestionConfig as POST /api/v1/question-configs Credit Cost: 1

Этот конечный пункт API позволяет создать QuestionConfig.

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

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/question-configs?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some name that shows on reports.",
    "question": "how much do you like this api?",
    "type": 'slider',
    "reportingOrder": 0,
    "min": 0,
    "max": 10
}'

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

Copy

interface QuestionConfigPostQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface QuestionConfigPostResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input';  
    /** Включается при ошибке. **/
    reason?: string
    /** Созданный объект. **/
    questionConfig?: QuestionConfig
}

PATCH /api/v1/question-configs/:id

Resource: QuestionConfig as PATCH /api/v1/question-configs/:id Credit Cost: 1

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

Ниже приведена структура со всеми значениями, которые можно изменить:

Структура QuestionConfig

Copy

interface QuestionConfigPatchBody {
    name?: string
    question?: string
    helpText?: string
    /** Внимание! Изменение type может нарушить отчётность, если min/max отличаются. **/
    type?: QuestionConfigType
    numStars?: number
    min?: number
    max?: number
    defaultValue?: number
    labelNegative?: string
    labelPositive?: string
    subQuestionIds?: string[]
    alwaysShowSubQuestions?: boolean
    reportingOrder?: number
}

Пример cURL обновления QuestionConfig

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/question-configs/my-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "question": "some new question text"
}'

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

Copy

interface QuestionConfigPatchQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface QuestionConfigPatchResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'unauthorized' | 'missing-api-key' | 'missing-id' | 'not-found' | 'empty-request' | 'invalid-input'
    /** Включается при ошибке. **/
    reason?: string
}

DELETE /api/v1/question-configs/:id

Resource: QuestionConfig as DELETE /api/v1/question-configs/:id Credit Cost: 100

Этот маршрут позволяет удалить QuestionConfig по id.

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

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

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/question-configs/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

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

Copy

interface QuestionConfigDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface QuestionConfigResponse {
    status: 'success' | 'failed'
    /** Указывается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Указывается при ошибке. **/
    reason?: string
}

Структура результата вопроса

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

Структура QuestionResult

Copy

interface QuestionResultMeta {
    name: string
    values: string[]
}
interface QuestionResult {
    id: string
    tenantId: string
    urlId: string
    anonUserId?: string
    userId?: string
    createdAt?: string
    value: number
    commentId?: string
    questionId: string
    meta?: QuestionResultMeta[]
}

GET /api/v1/question-results

Resource: QuestionResults as GET /api/v1/question-results Credit Cost: 1

Этот маршрут возвращает до 1000 объектов QuestionResults за раз, с пагинацией. Стоимость — 1 за каждые 100 объектов. Они отсортированы по createdAt в порядке возрастания. Вы можете фильтровать по различным параметрам.

Пример QuestionResults

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/question-results?tenantId=demo&API_KEY=DEMO_API_SECRET'

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

Copy

interface QuestionResultsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** Для пагинации. Нумерация начинается с 0. **/
    skip?: number
    /** Для пагинации. **/
    limit?: number
    /** Получить результаты с конкретной страницы. **/
    urlId?: string
    /** Получить результаты от конкретного пользователя. **/
    userId?: string
    startDate?: string | number
    questionId?: string | string[]
}

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

Copy

interface QuestionResultsResponse {
    status: 'success' | 'failed'
    /** Присутствует при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Присутствует при ошибке. **/
    reason?: string
    questionResults: QuestionResults[]
}

GET /api/v1/question-results/:id

Resource: QuestionResult as GET /api/v1/question-results/:id Credit Cost: 1

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

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

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/question-results/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

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

Copy

interface QuestionResultRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface QuestionResultByIdResponse {
    status: 'success' | 'failed'
    /** Указывается в случае ошибки. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Указывается в случае ошибки. **/
    reason?: string
    questionResult?: QuestionResult
}

POST /api/v1/question-results

Resource: QuestionResult as POST /api/v1/question-results Credit Cost: 1

Этот эндпоинт API позволяет создать QuestionResult.

Пример cURL-запроса для QuestionResult (POST)

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/question-results?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "urlId": "some-page-id",
    "anonUserId": 'anon-0',
    "userId": 'user-0',
    "value": 10,
    "questionId": "some-question-id",
    "meta": [
        {
            name: "example",
            values: ["value-1", "value-2"]
        }
    ]
}'

Структура POST-запроса QuestionResult

Copy

interface QuestionResultPostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура POST-ответа QuestionResult

Copy

interface QuestionResultPostResponse {
    status: 'success' | 'failed'
    /** Включается при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input';  
    /** Включается при ошибке. **/
    reason?: string
    /** Созданный объект. **/
    questionResult?: QuestionResult
}

PATCH /api/v1/question-results/:id

Resource: QuestionResult as PATCH /api/v1/question-results/:id Credit Cost: 1

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

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

Структура QuestionResult

Copy

interface QuestionResultPatchBody {
    urlId?: string
    anonUserId?: string
    userId?: string
    value?: string
    commentId?: string
    questionId?: string
    meta?: QuestionResultMeta[]
}

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

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/question-results/my-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "value": 5
}'

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

Copy

interface QuestionResultPatchQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface QuestionResultPatchResponse {
    status: 'success' | 'failed'
    /** Присутствует при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'unauthorized' | 'missing-api-key' | 'missing-id' | 'not-found' | 'empty-request' | 'invalid-input'
    /** Присутствует при ошибке. **/
    reason?: string
}

DELETE /api/v1/question-results/:id

Resource: QuestionResult as DELETE /api/v1/question-results/:id Credit Cost: 1

Этот маршрут предоставляет удаление QuestionResult по id.

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

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/question-results/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

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

Copy

interface QuestionResultDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface QuestionResultResponse {
    status: 'success' | 'failed'
    /** Включено при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Включено при ошибке. **/
    reason?: string
}

GET /api/v1/question-results-aggregate

Resource: QuestionResultsAggregate as GET /api/v1/question-results-aggregate Credit Cost: 2

Здесь выполняется агрегирование результатов.

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

Структура QuestionResultsAggregationResult

Copy

interface QuestionResultDataPoint {
    /** Карта значения к количеству появлений этого значения для текущей точки данных (дата-бакет или страница). **/
    v: Map<ValueAsString, number>
    total: number
}
interface QuestionResultsAggregationResult {
    /** Примечание — имеет значение null, когда timeBucket не указан. **/
    dataByDateBucket?: Map<DateString, QuestionResultDataPoint>
    dataByUrlId?: Map<URLIdString, QuestionResultDataPoint>
    countsByValue?: Map<ValueAsString, number>
    /** Общее число агрегированных результатов. **/
    total: number
    /** Получившееся взвешенное среднее. Это число с плавающей запятой, обычно с двумя знаками после запятой или меньше. **/
    average: number
    /** Строка даты, указывающая, когда эти данные были вычислены, так как они могли быть взяты из кэша. **/
    createdAt: string
}

Ниже перечислены параметры запроса, доступные для агрегирования:

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

Copy

interface QuestionResultsAggregateRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** Вы можете агрегировать результаты для одного или нескольких вопросов. **/
    questionId: string | string[]
    startDate?: string | number
    timeBucket?: 'day' | 'month' | 'year'
    /** Aggregate for a specific page. **/
    urlId?: string
    /** Aggregate for a specific user. **/
    userId?: string
    /** Force recalculate now and update the cache. **/
    forceRecalculate?: boolean
}

Пример запроса:

Пример запроса QuestionResultsAggregation

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/question-results-aggregation?tenantId=demo&API_KEY=DEMO_API_SECRET&questionId=some-question-id'

Пример ответа:

Пример ответа QuestionResultsAggregation

Copy

    {
        "average": 8.33,
        "countsByValue": {
            "5": 1,
            "10": 2
        },
        "createdAt": "2023-08-30T00:00:00.000Z",
        "dataByUrlId": {
            "some-page": {
                "total": 3,
                "v": {
                    "5": 1,
                    "10": 2
                }
            }
        },
        "total": 3
    }

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

Copy

interface QuestionResultsAggregationResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    data: QuestionResultsAggregationResult
}

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

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

Примечания по кэшированию и стоимости

Когда forceRecalculate указан, стоимость всегда равна 10, вместо обычных 2.
Если кэш истёк и данные пересчитываются, стоимость по-прежнему составляет константные 2, если forceRecalculate не указан. Срок жизни кэша зависит от объёма агрегируемого набора данных (может варьироваться от 30 секунд до 5 минут).
Это сделано для поощрения использования кэша.

GET /api/v1/question-results-aggregate/combine/comments

Resource: QuestionResultsCombinedWithComments as GET /api/v1/question-results-aggregate/combine/comments Credit Cost: 2

Здесь происходит объединение результатов с комментариями. Полезно, например, для создания диаграммы «последние положительные и отрицательные комментарии» для продукта.

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

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

Структура QuestionResultsCombinedWithCommentsResponse

Copy

interface SimpleComment {
    id: string
    commenterName: string
    userId?: string
    date: string
    commentHTML: string
}
interface SimpleQuestionResult {
    id: string
    value: number
}
interface CommentAndResult {
    comment: SimpleComment
    result: SimpleQuestionResult
}
interface QuestionResultsCombinedWithCommentsResponse {
    /** Строка с датой, указывающая, когда эти данные были вычислены, так как они могут быть из кэша. **/
    createdAt: string
    results: CommentAndResult[]
}

Ниже перечислены параметры запроса, доступные для агрегации:

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

Copy

interface QuestionResultsAggregateRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** Вы можете агрегировать результаты для одного или нескольких вопросов. **/
    questionId: string | string[]
    startDate?: string | number
    urlId?: string
    minValue: number
    maxValue: number
    limit?: number
    forceRecalculate?: boolean
}

Пример запроса:

Пример QuestionResultsCombineComments

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/question-results-aggregation/combine/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&questionId=some-question-id&minValue=5&maxValue=10'

Пример ответа:

Пример ответа QuestionResultsCombineComments

Copy

{
    "createdAt": "2023-08-30T00:00:00.000Z",
    "results": [
        {
            "comment": {
                "id": "some-id",
                "commentHTML": "test-2",
                "commenterName": "Test",
                "date": "2023-08-30T00:00:00.000Z",
                "userId": "some-user-id"
            },
            "result": {
                "id": "some-id",
                "value": 10
            }
        },
        {
            "comment": {
                "id": "some-id",
                "commentHTML": "test-0",
                "commenterName": "Some Name",
                "date": "2023-08-30T00:00:00.000Z",
                "userId": "some-user-id"
            },
            "result": {
                "id": "some-id",
                "value": 5
            }
        }
    ]
}

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

Copy

interface QuestionResultsCombineCommentsResponse {
    status: 'success' | 'failed'
    /** Включено при ошибке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Включено при ошибке. **/
    reason?: string
    data: QuestionResultsCombinedWithCommentsResponse
}

Примечания по кэшированию и стоимости

Когда указан forceRecalculate, стоимость всегда равна 10, вместо обычных 2.
Если кэш истекает и данные пересчитываются, стоимость всё равно остаётся 2, если forceRecalculate не указан.
Это сделано для стимулирования использования кэша.

Структура значка пользователя

UserBadge — это объект, представляющий бейдж, присвоенный пользователю в системе FastComments.

Бейджи могут присваиваться пользователям автоматически на основе их активности (например, количества комментариев, времени ответа, статуса Veteran) или вручную администраторами сайта.

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

Структура UserBadge

Copy

export interface UserBadge {
    /** Уникальный идентификатор этого назначения бейджа пользователю */
    id: string
    /** ID пользователя, которому присвоен этот бейдж */
    userId: string
    /** ID определения бейджа из каталога бейджей арендатора */
    badgeId: string
    /** ID арендатора, который создал/присвоил этот бейдж */
    fromTenantId: string
    /** Когда этот бейдж был создан (миллисекунды с начала эпохи) */
    createdAt?: number
    /** Когда этот бейдж был получен пользователем (миллисекунды с начала эпохи) */
    receivedAt?: number
    /** 
     * Тип бейджа: 
     * 0=CommentCount, 1=CommentUpVotes, 2=CommentReplies, 3=CommentsPinned, 
     * 4=Veteran, 5=NightOwl, 6=FastReplyTime, 7=ModeratorCommentsDeleted,
     * 8=ModeratorCommentsApproved, 9=ModeratorCommentsUnapproved, 10=ModeratorCommentsReviewed,
     * 11=ModeratorCommentsMarkedSpam, 12=ModeratorCommentsMarkedNotSpam, 13=RepliedToSpecificPage,
     * 14=Manual
     */
    type: number
    /** Для бейджей, основанных на пороге, значение порога */
    threshold?: number
    /** Название/метка бейджа */
    name?: string
    /** Подробное описание бейджа */
    description?: string
    /** Текст, отображаемый на бейдже */
    displayLabel?: string
    /** URL изображения, отображаемого на бейдже */
    displaySrc?: string
    /** Цвет фона бейджа (hex-код) */
    backgroundColor?: string
    /** Цвет границы бейджа (hex-код) */
    borderColor?: string
    /** Цвет текста бейджа (hex-код) */
    textColor?: string
    /** Дополнительный CSS-класс для стилизации */
    cssClass?: string
    /** Для бейджей типа Veteran, порог времени в миллисекундах */
    veteranUserThresholdMillis?: number
    /** Отображается ли этот бейдж на комментариях пользователя */
    displayedOnComments: boolean
    /** Порядок отображения бейджа */
    order?: number
}

GET /api/v1/user-badges

This endpoint allows you to fetch user badges based on various criteria.

Пример запроса:

Пример GET-запроса

Copy

Run

curl -X GET "https://fastcomments.com/api/v1/user-badges?tenantId=demo&API_KEY=DEMO_API_SECRET"

Вы можете добавить различные параметры запроса для фильтрации результатов:

userId - Получить значки для конкретного пользователя
badgeId - Получить экземпляры конкретного значка
type - Фильтровать по типу значка (0=CommentCount, 1=CommentUpVotes, 2=CommentReplies, etc. See UserBadge structure for full list)
displayedOnComments - Фильтровать по тому, отображается ли значок в комментариях (true/false)
limit - Максимальное количество возвращаемых значков (по умолчанию 30, макс 200)
skip - Количество пропускаемых значков (для пагинации)

Пример ответа:

Ответ

Copy

{
  "status": "success",
  "userBadges": [
    {
      "id": "badge123",
      "userId": "user456",
      "badgeId": "badgeDef789",
      "fromTenantId": "tenant001",
      "createdAt": 1650532511000,
      "receivedAt": 1650532511000,
      "type": 14,
      "name": "Special Contributor",
      "description": "Awarded to special contributors to our community",
      "displayLabel": "Special",
      "backgroundColor": "#4a5568",
      "textColor": "#ffffff",
      "displayedOnComments": true,
      "order": 1
    },
    {
      "id": "badge124",
      "userId": "user456",
      "badgeId": "badgeDef790",
      "fromTenantId": "tenant001",
      "createdAt": 1650532598000,
      "receivedAt": 1650532598000,
      "type": 0,
      "threshold": 100,
      "name": "Centurion",
      "description": "Made 100 comments",
      "displayLabel": "100",
      "backgroundColor": "#2b6cb0",
      "textColor": "#ffffff",
      "displayedOnComments": true,
      "order": 2
    }
  ]
}

Возможные ответы об ошибке:

Ошибка: отсутствует Tenant ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Ошибка: недопустимый limit

Copy

{
  "status": "failed",
  "code": "invalid-limit",
  "reason": "The limit (query param: limit) is too large (> 200)."
}

---

GET /api/v1/user-badges/:id

Этот endpoint позволяет получить конкретный бейдж пользователя по его уникальному ID.

Пример запроса:

Пример GET-запроса

Copy

Run

curl -X GET "https://fastcomments.com/api/v1/user-badges/badge123?tenantId=demo&API_KEY=DEMO_API_SECRET"

Пример ответа:

Ответ

Copy

{
  "status": "success",
  "userBadge": {
    "id": "badge123",
    "userId": "user456",
    "badgeId": "badgeDef789",
    "fromTenantId": "tenant001",
    "createdAt": 1650532511000,
    "receivedAt": 1650532511000,
    "type": 14,
    "name": "Special Contributor",
    "description": "Awarded to special contributors to our community",
    "displayLabel": "Special",
    "backgroundColor": "#4a5568",
    "textColor": "#ffffff",
    "displayedOnComments": true,
    "order": 1
  }
}

Возможные ответы с ошибкой:

Ошибка: Отсутствует ID арендатора

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Ошибка: Не найдено

Copy

{
  "status": "failed",
  "code": "not-found",
  "reason": "The user badge badge123 was not found."
}

POST /api/v1/user-badges

This endpoint позволяет вам создать новое присвоение значка пользователю.

Example Request:

Пример POST-запроса

Copy

Run

curl -X POST "https://fastcomments.com/api/v1/user-badges?tenantId=demo&API_KEY=DEMO_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
  "userId": "user456",
  "badgeId": "badgeDef789",
  "displayedOnComments": true
}'

The request body must contain the following parameters:

userId (обязательно) - ID пользователя, которому присвоят значок
badgeId (обязательно) - ID значка для присвоения
displayedOnComments (необязательно) - Должен ли значок отображаться в комментариях пользователя (по умолчанию true)

Important Notes:

Значок должен существовать и быть включён в каталог значков вашего тенанта
Вы можете присваивать значки только пользователям, которые принадлежат вашему тенанту или оставляли комментарии на вашем сайте

Example Response:

Ответ

Copy

{
  "status": "success",
  "userBadge": {
    "id": "badge123",
    "userId": "user456",
    "badgeId": "badgeDef789",
    "fromTenantId": "tenant001",
    "createdAt": 1650532511000,
    "receivedAt": 1650532511000,
    "type": 14,
    "name": "Special Contributor",
    "description": "Awarded to special contributors to our community",
    "displayLabel": "Special",
    "backgroundColor": "#4a5568",
    "textColor": "#ffffff",
    "displayedOnComments": true,
    "order": 1
  }
}

Possible Error Responses:

Ошибка: отсутствует идентификатор тенанта

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Ошибка: отсутствует идентификатор пользователя

Copy

{
  "status": "failed",
  "code": "missing-user-id",
  "reason": "User ID (body param: userId) is required."
}

Ошибка: отсутствует идентификатор значка

Copy

{
  "status": "failed",
  "code": "missing-badge-id",
  "reason": "Badge ID (body param: badgeId) is required."
}

Ошибка: значок не найден

Copy

{
  "status": "failed",
  "code": "badge-not-found",
  "reason": "The badge badgeDef789 was not found or is not enabled."
}

Ошибка: неавторизованный пользователь

Copy

{
  "status": "failed",
  "code": "unauthorized-user",
  "reason": "You can only add badges to users who belong to your tenant or have commented on your site."
}

PUT /api/v1/user-badges/:id

Этот endpoint позволяет обновить назначение значка пользователя.

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

Example Request:

Пример PUT-запроса

Copy

Run

curl -X PUT "https://fastcomments.com/api/v1/user-badges/badge123?tenantId=demo&API_KEY=DEMO_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
  "displayedOnComments": false
}'

Example Response:

Ответ

Copy

{
  "status": "success"
}

Possible Error Responses:

Ошибка: отсутствует Tenant ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Ошибка: отсутствует ID

Copy

{
  "status": "failed",
  "code": "missing-id",
  "reason": "The User Badge ID (url param: id) is missing."
}

Ошибка: не найдено

Copy

{
  "status": "failed",
  "code": "not-found",
  "reason": "The user badge badge123 was not found."
}

---

DELETE /api/v1/user-badges/:id

Этот конечный пункт API позволяет удалить назначение значка пользователя.

Example Request:

Пример DELETE-запроса

Copy

Run

curl -X DELETE "https://fastcomments.com/api/v1/user-badges/badge123?tenantId=demo&API_KEY=DEMO_API_SECRET"

Example Response:

Ответ

Copy

{
  "status": "success"
}

Possible Error Responses:

Ошибка: Отсутствует Tenant ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Ошибка: Отсутствует ID

Copy

{
  "status": "failed",
  "code": "missing-id",
  "reason": "The User Badge ID (url param: id) is missing."
}

Ошибка: Не найдено

Copy

{
  "status": "failed",
  "code": "not-found",
  "reason": "The user badge badge123 was not found."
}

---

Структура прогресса значка пользователя

UserBadgeProgress — это объект, который представляет прогресс пользователя в получении различных значков в системе FastComments.

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

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

Структура UserBadgeProgress

Copy

export interface UserBadgeProgress {
    /** Уникальный идентификатор этой записи прогресса */
    id: string
    /** ID тенанта, которому принадлежит эта запись прогресса */
    tenantId: string
    /** ID пользователя, за которым отслеживается эта запись прогресса */
    userId: string
    /** ID первого комментария пользователя в системе */
    firstCommentId?: string
    /** Дата первого комментария пользователя (миллисекунды с начала эпохи Unix) */
    firstCommentDate?: number
    /** Автоматически рассчитанный коэффициент доверия на основе активности пользователя */
    autoTrustFactor?: number
    /** Коэффициент доверия, установленный вручную администраторами */
    manualTrustFactor?: number
    /** Подробный объект прогресса с различными метриками, ключи соответствуют перечислению BadgeType */
    progress: {
        /** 0: CommentCount - Количество комментариев, оставленных пользователем */
        '0'?: number
        /** 1: CommentUpVotes - Количество полученных пользователем голосов 'за' */
        '1'?: number
        /** 2: CommentReplies - Количество ответов, оставленных пользователем */
        '2'?: number
        /** 3: CommentsPinned - Количество закреплённых комментариев у пользователя */
        '3'?: number
        /** 4: Veteran - Возраст аккаунта пользователя */
        '4'?: number
        /** 5: NightOwl - Количество раз, когда пользователь публиковал в ночное время */
        '5'?: number
        /** 6: FastReplyTime - Среднее время ответа в миллисекундах */
        '6'?: number
        /** 7: ModeratorCommentsDeleted - Для бейджей модератора, количество удалённых комментариев */
        '7'?: number
        /** 8: ModeratorCommentsApproved - Для бейджей модератора, количество одобренных комментариев */
        '8'?: number
        /** 9: ModeratorCommentsUnapproved - Для бейджей модератора, количество неодобренных комментариев */
        '9'?: number
        /** 10: ModeratorCommentsReviewed - Для бейджей модератора, количество проверенных комментариев */
        '10'?: number
        /** 11: ModeratorCommentsMarkedSpam - Для бейджей модератора, количество помеченных как спам комментариев */
        '11'?: number
        /** 12: ModeratorCommentsMarkedNotSpam - Для бейджей модератора, количество помеченных как 'не спам' комментариев */
        '12'?: number
        /** 13: RepliedToSpecificPage - Для каждой страницы, количество ответов */
        '13'?: Record<string, number>
    }
}

GET /api/v1/user-badge-progress

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

Пример запроса:

Пример GET-запроса

Copy

Run

curl -X GET "https://fastcomments.com/api/v1/user-badge-progress?tenantId=demo&API_KEY=DEMO_API_SECRET"

Вы можете добавить различные параметры запроса для фильтрации результатов:

userId - Получить прогресс для конкретного пользователя
limit - Максимальное количество записей для возврата (по умолчанию 30, максимум 200)
skip - Число записей для пропуска (для пагинации)

Пример ответа:

Ответ

Copy

{
  "status": "success",
  "userBadgeProgresses": [
    {
      "id": "progress123",
      "tenantId": "tenant001",
      "userId": "user456",
      "firstCommentId": "comment789",
      "firstCommentDate": 1650532511000,
      "autoTrustFactor": 0.75,
      "progress": {
        "0": 42,
        "1": 120,
        "2": 15,
        "3": 3,
        "5": 5,
        "6": 1800000,
        "8": 0,
        "7": 0
      }
    },
    {
      "id": "progress124",
      "tenantId": "tenant001",
      "userId": "user789",
      "firstCommentId": "comment790",
      "firstCommentDate": 1650532598000,
      "autoTrustFactor": 0.5,
      "progress": {
        "0": 12,
        "1": 15,
        "2": 4
      }
    }
  ]
}

Возможные ответы с ошибками:

Ошибка: отсутствует ID арендатора

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Ошибка: недопустимый параметр limit

Copy

{
  "status": "failed",
  "code": "invalid-limit",
  "reason": "The limit (query param: limit) is too large (> 200)."
}

GET /api/v1/user-badge-progress/:id

This endpoint allows you to fetch a specific user badge progress record by its unique ID.

Пример запроса:

Пример запроса GET

Copy

Run

curl -X GET "https://fastcomments.com/api/v1/user-badge-progress/progress123?tenantId=demo&API_KEY=DEMO_API_SECRET"

Пример ответа:

Ответ

Copy

{
  "status": "success",
  "userBadgeProgress": {
    "id": "progress123",
    "tenantId": "tenant001",
    "userId": "user456",
    "firstCommentId": "comment789",
    "firstCommentDate": 1650532511000,
    "autoTrustFactor": 0.75,
    "progress": {
      "0": 42,
      "1": 120,
      "2": 15,
      "3": 3,
      "5": 5,
      "6": 1800000,
      "8": 0,
      "7": 0
    }
  }
}

Возможные ответы с ошибкой:

Ошибка: Отсутствует Tenant ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Ошибка: Не найдено

Copy

{
  "status": "failed",
  "code": "not-found",
  "reason": "The user badge progress progress123 was not found."
}

GET /api/v1/user-badge-progress/user/:userId

Этот эндпоинт позволяет получить запись о прогрессе бейджа пользователя по его User ID.

Пример запроса:

Пример GET-запроса

Copy

Run

curl -X GET "https://fastcomments.com/api/v1/user-badge-progress/user/user456?tenantId=demo&API_KEY=DEMO_API_SECRET"

Пример ответа:

Ответ

Copy

{
  "status": "success",
  "userBadgeProgress": {
    "id": "progress123",
    "tenantId": "tenant001",
    "userId": "user456",
    "firstCommentId": "comment789",
    "firstCommentDate": 1650532511000,
    "autoTrustFactor": 0.75,
    "progress": {
      "0": 42,
      "1": 120,
      "2": 15,
      "3": 3,
      "5": 5,
      "6": 1800000,
      "8": 0,
      "7": 0
    }
  }
}

Возможные ответы с ошибкой:

Ошибка: Отсутствует Tenant ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Ошибка: Отсутствует User ID

Copy

{
  "status": "failed",
  "code": "missing-user-id",
  "reason": "The User ID (path param: userId) is missing."
}

Ошибка: Не найдено

Copy

{
  "status": "failed",
  "code": "not-found",
  "reason": "No badge progress found for user user456 in tenant tenant001."
}

В заключение

Надеемся, что наша документация по API была для вас исчерпывающей и понятной. Если вы обнаружите какие-либо пробелы, сообщите нам об этом ниже.

Язык 🇺🇦 Русский (Украина)

Ресурсы API

Агрегации

Журналы аудита

Комментарии

Шаблоны писем

Хэштеги

Модераторы

Счётчик уведомлений

Уведомления

Страницы

Ожидающие события вебхука

SSO-пользователи

Подписки

Ежедневное использование тенанта

Тенанты

Пакеты тенанта

Пользователи тенанта

Пользователи

Голоса

Конфигурации домена

Конфигурации вопросов

Результаты вопросов

Агрегация результатов вопросов

Значки пользователей

Прогресс значка пользователя

The FastComments API

Generated SDKs

Authentication

Security Note

Authentication Option One - Headers

Authentication Option Two - Query Parameters

Ресурсы API

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

Примечание!

Агрегирование данных

Примеры

Пример: Подсчёт уникальных значений

Пример: Подсчёт количества различных значений

Пример: Суммирование значений нескольких полей

Пример: Средние значения нескольких полей

Пример: Минимальные/максимальные значения нескольких полей

Пример: Подсчёт уникальных значений нескольких полей

Пример: Создание запроса

Пример: Подсчёт комментариев, ожидающих проверки

Пример: Разбивка по утверждённым, просмотренным и спам-комментариям

Структуры

Структура журнала аудита

GET /api/v1/audit-logs

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

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

Упоминания

Хэштеги

GET /api/v1/comments

Pagination

Threads

Trees Explained

Fetching Comments in The Context of a User

Get Comments as a Tree

Get Comments as a Tree, Searching by Hash Tag

All Request Params

The Response

Helpful Tips

URL ID

Anonymous Actions

Comments Not Being Returned

GET /api/v1/comments/:id

POST /api/v1/comments

PATCH /api/v1/comments/:id

DELETE /api/v1/comments/:id

POST /api/v1/comments/:id/flag

POST /api/v1/comments/:id/un-flag

POST /api/v1/comments/:id/block

POST /api/v1/comments/:id/un-block

Структура шаблона письма

Примечания

GET /api/v1/email-templates/:id

GET /api/v1/email-templates

PATCH /api/v1/email-templates/:id

POST /api/v1/email-templates