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

API FastComments

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

У цій документації ви знайдете всі підтримувані ресурси API, задокументовані з їх типами запитів та відповідей.

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

Згенеровані SDK

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

Тепер у нас також є SDK для популярних мов:

Аутентифікація

API аутентифікується шляхом передачі вашого api key як заголовка X-API-KEY або параметра запиту API_KEY. Вам також знадобиться ваш tenantId для здійснення викликів API. Його можна отримати на тій же сторінці, що й ваш api key.

Примітка щодо безпеки

Ці маршрути призначені для виклику з сервера. НЕ ВИКОРИСТОВУЙТЕ їх у браузері. Це розкриє ваш API-ключ — це надасть повний доступ до вашого облікового запису будь-кому, хто зможе переглянути вихідний код сторінки!

Варіант аутентифікації 1 — Заголовки

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

Варіант аутентифікації 2 — Параметри запиту

Query Param: API_KEY
Query Param: tenantId

Варіант аутентифікації 3 — OAuth Bearer Token

Header: Authorization: Bearer fcat_...

Треті сторони, такі як Zapier та клієнти MCP server, отримують токен через OAuth замість API-ключа. Цей токен працює на кожному кінцевому пункті тут. Орендар передбачений токеном, тому tenantId є необов’язковим, але має відповідати токену, якщо вказаний. Запити GET потребують області read, а всі інші методи — області write. Повний процес, включаючи реєстрацію клієнта, PKCE, оновлення та відкликання, задокументовано в розділі Авторизація OAuth. Відкриття починається за адресою https://fastcomments.com/.well-known/oauth-authorization-server.

Читання власних записів

FastComments забезпечує активну‑активну доступність. Запити з вашого дата‑центру маршрутизуються до найближчого пункту присутності до вас. Це автоматично, і зазвичай ви можете спостерігати семантику «читати‑те‑запис». Якщо ви хочете бути впевненими, що читаєте власні записи, ви можете прив’язати ваші запити до певного регіону, використовуючи цей регіон як хост API (хоча зазвичай це не потрібно для більшості інтеграцій):

gdc-oregon.fastcomments.com
gdc-virginia.fastcomments.com
gdc-singapore.fastcomments.com
gdc-falkenstein2.fastcomments.com
gdc-sao-paulo.fastcomments.com
eudc-helsinki2.fastcomments.com
eudc-limburg.fastcomments.com
eudc-france.fastcomments.com

Зверніть увагу, що якщо ви це робите, можливо, захочете визначити резервний варіант, оскільки раніше ми деактивували вузли входу і використовуємо нові назви для перемикання.

Ресурси API

Використання ресурсів

Слід зазначити, що отримання даних з API враховується як використання вашого облікового запису.

Кожен ресурс буде вказувати, яке саме використання він має, у власному розділі.

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

Використання API можна перевірити на сторінці Billing Analytics і воно оновлюється кожні кілька хвилин.

Примітка!

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

Вебхуки

Підписки на вебхуки мають власний посібник. POST, GET і DELETE /api/v1/webhooks, а також GET /api/v1/webhooks/sample-payloads, задокументовані в розділі Managing Subscriptions via API, а структури подій — у Webhook Structures.

Авторизація OAuth

FastComments є сервером авторизації OAuth 2.1. Додаток може отримати токен, який прив’язаний до одного облікового запису FastComments, і використовувати його на кожному кінцевому пункті в цьому посібнику замість API‑ключа. Так підключаються додаток Zapier, сервер MCP та інші сторонні інтеграції.

Токени видаються через потік коду авторизації з PKCE. Не передбачено клієнтських облікових даних або неявного гранту.

Discovery

Розташування кінцевих точок, підтримувані гранти та методи автентифікації публікуються за стандартною URL‑адресою метаданих:

Метадані сервера авторизації

Copy

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

Кінцеві точки, які він описує:

Кінцеві точки OAuth

Copy

GET  https://fastcomments.com/oauth/authorize
POST https://fastcomments.com/oauth/token
POST https://fastcomments.com/oauth/revoke
POST https://fastcomments.com/oauth/register

Облікові записи в регіоні ЄС використовують https://eu.fastcomments.com як видавця, з тими ж шляхами.

Реєстрація клієнта

Клієнту потрібен client_id та зареєстрований redirect_uri, перш ніж він зможе розпочати процес. Існує два способи отримати їх:

Динамічна реєстрація клієнта. POST /oauth/register з JSON‑тілом згідно RFC 7591 (redirect_uris, client_name, client_uri, logo_uri, token_endpoint_auth_method). Відповідь містить client_id і, для конфіденційних клієнтів, client_secret. Реєстрація не потребує автентифікації та обмежена за швидкістю per IP.
Документ метаданих Client ID. Клієнт використовує https URL, яким він керує, як свій client_id. FastComments отримує цей URL і читає з нього ті ж поля метаданих. Виклик реєстрації не потрібен.

Партнерські додатки, зазначені в панелі FastComments, такі як Zapier, реєструються безпосередньо FastComments. Зверніться до підтримки, якщо ви створюєте запис у маркетплейсі і потрібен клієнт першої сторони.

Скоупи

Copy

read   GET and HEAD requests
write  every other method

Запит, який не вказує жодного скоупу, отримує обидва. Користувач бачить запитані скоупи на сторінці згоди. Запит на скоуп, відмінний від цих двох, завершується помилкою invalid_scope.

Крок 1 – Запит авторизації

Надішліть браузер користувача до кінцевої точки авторизації. PKCE з методом S256 є обов’язковим для кожного клієнта.

Запит авторизації

Copy

GET https://fastcomments.com/oauth/authorize
    ?response_type=code
    &client_id=YOUR_CLIENT_ID
    &redirect_uri=https://example.com/oauth/callback
    &scope=read%20write
    &state=RANDOM_STATE
    &code_challenge=BASE64URL_SHA256_OF_VERIFIER
    &code_challenge_method=S256

Параметри запиту авторизації

Copy

interface OAuthAuthorizeQueryParams {
    response_type: 'code'
    client_id: string
    /** Must exactly match one of the client's registered redirect URIs. **/
    redirect_uri: string
    /** Space separated. Omit to request both scopes. **/
    scope?: 'read' | 'write' | 'read write'
    /** Returned unchanged on the redirect. Use it to bind the callback to the session that started the flow. **/
    state?: string
    /** base64url(sha256(code_verifier)). **/
    code_challenge: string
    code_challenge_method: 'S256'
    /** Optional RFC 8707 resource indicator. If sent, the same value must be sent to the token endpoint. **/
    resource?: string
}

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

Код авторизації дійсний протягом 10 хвилин і може бути обміняний один раз. Другий обмін тим же кодом відкликає всі токени, створені під час першого обміну.

Крок 2 – Запит токену

Обміняйте код на токени. Тіло запиту кодується у форматі form. Конфіденційні клієнти автентифікуються за допомогою client_secret_basic (HTTP Basic) або client_secret_post (секрет у тілі). Публічні клієнти надсилають лише client_id.

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

Copy

curl --request POST \
  --url 'https://fastcomments.com/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code' \
  --data 'client_id=YOUR_CLIENT_ID' \
  --data 'client_secret=YOUR_CLIENT_SECRET' \
  --data 'code=fcac_...' \
  --data 'code_verifier=YOUR_PKCE_VERIFIER' \
  --data 'redirect_uri=https://example.com/oauth/callback'

Тіло запиту токену (authorization_code)

Copy

interface OAuthTokenRequestAuthorizationCode {
    grant_type: 'authorization_code'
    client_id: string
    /** Confidential clients only. May be sent as HTTP Basic auth instead. **/
    client_secret?: string
    code: string
    code_verifier: string
    /** Must match the authorization request when sent. **/
    redirect_uri?: string
    resource?: string
}

Структура відповіді токену

Copy

interface OAuthTokenResponse {
    /** Prefixed fcat_. Valid for one hour. **/
    access_token: string
    token_type: 'bearer'
    /** Seconds until the access token expires. 3600. **/
    expires_in: number
    /** Prefixed fcrt_. Valid for 30 days from issue. **/
    refresh_token: string
    /** Space separated scopes granted. **/
    scope: string
}

Помилки відповідають RFC 6749: JSON‑тіло з error та error_description, HTTP 400 для invalid_request, invalid_grant, invalid_scope, invalid_target та unsupported_grant_type, HTTP 401 для invalid_client, HTTP 429 при обмеженні швидкості.

Крок 3 – Виклик API

Надішліть токен доступу як токен типу bearer. Орендар (tenant) передбачений токеном, тому tenantId є необов’язковим. Якщо вказано, він має збігатися з токеном, інакше запит завершиться помилкою.

Приклад cURL запиту Bearer токену

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/me' \
  --header 'Authorization: Bearer fcat_...'

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

Крок 4 – Оновлення

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

Copy

curl --request POST \
  --url 'https://fastcomments.com/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=refresh_token' \
  --data 'client_id=YOUR_CLIENT_ID' \
  --data 'client_secret=YOUR_CLIENT_SECRET' \
  --data 'refresh_token=fcrt_...'

Тіло запиту токену (refresh_token)

Copy

interface OAuthTokenRequestRefreshToken {
    grant_type: 'refresh_token'
    client_id: string
    client_secret?: string
    refresh_token: string
    /** Optional. Narrows to a subset of the scopes originally granted. **/
    scope?: string
    resource?: string
}

Відповідь має ту ж структуру, що й обмін кодом. Токени оновлення обертаються: кожне оновлення повертає новий refresh_token і відкликає старий після 30‑секундного вікна для одночасних запитів. Надання токену оновлення, який був обернений більше ніж 30 секунд тому, розглядається як повтор і відкликає весь грант. Партнерські додатки, зареєстровані FastComments, звільнені від обертання і отримують той самий токен оновлення з продовженим терміном дії ще на 30 днів.

Оновлення також перевіряє, чи користувач, що авторизував, все ще має дозвіл API Admin на обліковому записі. Якщо ні, грант відкликається, і відповідь містить invalid_grant.

Відкликання

Приклад cURL запиту відкликання

Copy

curl --request POST \
  --url 'https://fastcomments.com/oauth/revoke' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'client_id=YOUR_CLIENT_ID' \
  --data 'client_secret=YOUR_CLIENT_SECRET' \
  --data 'token=fcrt_...' \
  --data 'token_type_hint=refresh_token'

Відкликання токену оновлення відкликає всі токени доступу, видані в рамках того ж гранту. Відкликання токену доступу відкликає лише цей токен. Кінцева точка повертає HTTP 200 з порожнім JSON‑об’єктом, незалежно від того, чи був токен знайдений, згідно RFC 7009.

Користувачі також можуть відкликати підключення у розділі Connected Apps в панелі FastComments. Усі токени для цього додатку перестають працювати одразу.

Агрегуйте ваші дані

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

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

Вартість є змінною. Кожні 500 об'єктів, що скануються, коштують 1 кредит API.

За замовчуванням максимальне використання пам'яті на один виклик API становить 64MB, і за замовчуванням ви можете мати лише одну агрегацію, що працює одночасно. Якщо ви надішлете кілька агрегацій одночасно, вони будуть поставлені в чергу й виконані в порядку надходження. Очікувані агрегації чекатимуть максимум 60 секунд, після чого запит завершиться тайм-аутом. Окремі агрегації можуть виконуватися до 5 хвилин.

Якщо у вас є managed tenants, ви можете агрегувати всі ресурси дочірніх tenants в одному виклику, передавши параметр запиту 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

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

An AuditLog is an object that represents an audited event for tenants that have access to this feature.

The structure for the AuditLog object is as follows:

Структура AuditLog

Copy

interface AuditLog {
    id: string;
    /** Who performed the event. **/
    userId?: string;
    username?: string;
    resourceName: string;
    crudType: 'c' | 'r' | 'u' | 'd' | 'login';
    from: string;
    url?: string;
    ip?: string;
    /** The browser that performed the event, when it came from one. **/
    ua?: string;
    /** A hash of the session the event came from, for correlating one person's actions. Never the session itself. **/
    sIdHashed?: string;
    when: string;
    description?: string;
    serverStartDate: string;
    /** The id of the object the event was performed on, as opposed to who performed it. **/
    targetId?: string;
    /** A human-readable label for that object, e.g. "jsmith (jsmith@example.com)". **/
    targetLabel?: string;
    objectDetails?: object;
}

targetId і targetLabel описують, на що була виконана подія; userId і username описують, хто її виконав. Для оновлень objectDetails.changes містить карту {field: {from, to}}, що показує, що саме змінилося.

Журнал аудиту є незмінним. Його також не можна записувати вручну. FastComments.com може вирішувати, коли записувати в журнал аудиту. Однак ви можете читати його за допомогою цього API.

Події в журналі аудиту видаляються через два роки.

GET /api/v1/audit-logs

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

Цей API використовує пагінацію, яку забезпечують параметри skip, limit, before та after. AuditLogs повертаються сторінками по 1000 записів за замовчуванням, до максимальної limit у 10000, впорядковані за when та id. Сторінки великі, оскільки цей кінцевий пункт зазвичай використовується для вивантаження історії, а не для інтерактивного перегортання.

Кожні 100 повернутих записів коштують 1 кредит.

За замовчуванням ви отримуєте список з найновішими елементами спочатку. Таким чином, ви можете опитувати, починаючи з skip=0, пагінуючи, доки не знайдете останній запис, який ви спожили.

Альтернативно, ви можете сортувати за найстарішими спочатку і пагінувати, доки не залишиться записів.

Сортування можна виконати, встановивши order у ASC або DESC. За замовчуванням — DESC.

Запит за датою можливий за допомогою before та after у вигляді міток часу з мілісекундами. before і after НЕ включають зазначені значення, і кожен з них можна використовувати окремо.

Пошук того, що сталося з особою

Кожна подія реєструє, хто її виконав (username, userId, ip) і, окремо, над чим вона була виконана. targetLabel — це зрозуміла людям мітка для цього об’єкта, наприклад jsmith (jsmith@example.com), а targetId — його ідентифікатор. Використовуйте target для нечутливого до регістру пошуку підрядка в мітці, коли ви знаєте ім’я або електронну пошту особи, але не її ідентифікатор.

Видалення зберігає мітку на момент події, тому видалений користувач або модератор можуть бути ідентифіковані навіть після того, як базовий запис зник.

Керовані орендарі

Якщо ваш орендар керує іншими орендарями, встановіть includeManagedTenants=true, щоб отримати події як від вашого орендаря, так і від усіх орендарів, якими він керує, в одному відповіді. tenantId кожного поверненого запису вказує, від якого орендаря він походить.

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

Copy

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 AuditLogsRequestQueryParams {
    tenantId: string
    API_KEY: string
    order?: 'ASC' | 'DESC'
    /** Макс 10000. За замовчуванням 1000. **/
    limit?: number
    skip?: number
    before?: number
    after?: number
    /** Тільки події, виконані цим ім'ям користувача. **/
    username?: string
    /** Тільки події з цієї IP-адреси. **/
    ip?: string
    /** Тільки події цього типу. **/
    crudType?: 'c' | 'r' | 'u' | 'd' | 'login'
    /** Тільки події для цього ресурсу, напр. User або Moderator. **/
    resourceName?: string
    /** Тільки події, у яких уражений об’єкт має цей ідентифікатор. **/
    targetId?: string
    /** Пошук підрядка без урахування регістру в мітці ураженого об’єкта. **/
    target?: string
    /** Також повернути події від орендарів, якими керує цей орендар. **/
    includeManagedTenants?: boolean
}

Структура відповіді AuditLog

Copy

interface AuditLogsResponse {
    status: 'success' | 'failed'
    /** Включено у випадку помилки. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'invalid-limit' | 'invalid-skip'
    /** Включено у випадку помилки. **/
    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
    /** Електронна адреса коментатора. Обов'язкова, якщо анонімні коментарі вимкнені. **/
    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 коментаря. **/
    id: string
    /** Лише при створенні! Це хешується для збереження. **/
    ip?: string
    /** READONLY: Чи заблокував поточний користувач автора цього коментаря? **/
    isBlocked?: boolean
    /** READONLY: Чи автор коментаря є адміном? Встановлюється автоматично на основі userId. **/
    isByAdmin?: boolean
    /** READONLY: Чи автор коментаря є модератором? Встановлюється автоматично на основі userId. **/
    isByModerator?: boolean
    /** Встановити true, якщо коментар було м'яко видалено (була залишена тимчасова заміна через інші налаштування). **/
    isDeleted?: boolean
    /** Встановити true, якщо акаунт користувача було видалено і коментар потрібно було зберегти. **/
    isDeletedUser?: boolean
    /** READONLY: Чи було позначено (flagged) поточним увійденим користувачем (contextUserId)? **/
    isFlagged?: boolean
    /** Чи закріплено коментар? **/
    isPinned?: boolean
    /** Чи заблоковано коментар? Якщо true, ніхто (включно з модераторами) не може відповідати, редагувати або видаляти його, поки його не розблокують. **/
    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>
    /** Необов'язковий список id груп модерації, пов'язаних з цим коментарем. **/
    moderationGroupIds?: string[]|null
    /** READONLY: id об'єкта голосу, що відповідає голосу поточного користувача (contextUserId) за цей коментар. **/
    myVoteId?: string
    /** Чи було надіслано повідомлення про цей коментар коментаторам. Щоб запобігти надсиланню сповіщень під час імпорту, встановіть це в true. **/
    notificationSentForParent?: boolean
    /** Чи було надіслано повідомлення про цей коментар користувачам tenant. Щоб запобігти надсиланню сповіщень під час імпорту, встановіть це в true. **/
    notificationSentForParentTenant?: boolean
    /** Заголовок сторінки, на якій був цей коментар. **/
    pageTitle?: string
    /** Якщо ми відповідаємо на коментар, це ID коментаря, на який відповідаємо. **/
    parentId?: string|null
    /** Чи позначено коментар як переглянутий. **/
    reviewed: boolean
    /** id орендатора (tenant), до якого належить коментар. **/
    tenantId: string
    /** Користувач, який написав коментар. Створюється автоматично при збереженні коментаря з ім'ям/емейлом. **/
    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 {
    /** id користувача. Для 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 хештегу. **/
    id: string
    /** Фінальний текст #хештегу, включно зі символом #. **/
    tag: string
    /** Якщо хештег пов’язано з кастомним URL, він буде вказаний. **/
    url?: string
    /** Чи потрібно зберігати хештег, навіть якщо він не присутній у тексті коментаря при оновленні. Корисно для тегування коментарів без зміни тексту коментаря. **/
    retain?: boolean
}

GET /api/v1/comments

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

Цей API використовується для отримання коментарів для відображення користувачеві. Наприклад, він автоматично фільтрує непідтверджені або спам‑коментарі.

Пагінація

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

Найшвидший: Precalculated Pagination:
1. Так працює FastComments, коли ви використовуєте наші готові віджети та клієнти.
2. Натискання «next» просто збільшує номер сторінки.
3. Ви можете уявити це як отримання з сховища ключ‑значення.
4. У цьому випадку просто визначте параметр page, починаючи з 0, та напрямок сортування як direction.
5. Розміри сторінок можна налаштувати за допомогою правил кастомізації.
Найбільш гнучкий: 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.

Теми

При використанні Precalculated Pagination коментарі групуються за сторінкою, і коментарі в темах впливають на загальну сторінку.
1. У цьому випадку теми можна визначити на клієнті за допомогою parentId.
2. Наприклад, на сторінці з одним коментарем верхнього рівня та 29 відповідями, і встановивши page=0 у API — ви отримаєте лише коментар верхнього рівня та 29 дочірніх.
При використанні Flexible Pagination ви можете визначити параметр parentId.
1. Встановіть його в null, щоб отримати лише коментарі верхнього рівня.
2. Потім, щоб переглянути теми, викличте API ще раз і передайте parentId.
3. Типове рішення — зробити запит API для коментарів верхнього рівня, а потім паралельно виконати запити API, щоб отримати коментарі для дочірніх елементів кожного коментаря.
НОВЕ З лютого 2023! Отримуйте у вигляді дерева, використовуючи &asTree=true.
1. Ви можете уявити це як Flexible Pagination as a Tree.
2. Тільки коментарі верхнього рівня враховуються у пагінації.
3. Встановіть parentId=null, щоб розпочати дерево з кореня (ви повинні встановити parentId).
4. Встановіть skip та limit для пагінації.
5. Встановіть asTree у true.
6. Вартість у кредитах збільшується в 2x, оскільки наш бекенд повинен виконати значно більше роботи в цьому сценарії.
7. Встановіть maxTreeDepth, limitChildren та skipChildren за потребою.

Пояснення дерев

При використанні asTree може бути важко розібратись у пагінації. Ось зручна графіка:

Діаграма пагінації дерева

Отримання коментарів у контексті користувача

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

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

Коментарі попередньо обчислена пагінація

Copy

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'

Отримати коментарі у вигляді дерева

Можливо отримати коментарі у вигляді дерева, при цьому пагінація враховує лише коментарі верхнього рівня.

Коментарі у вигляді дерева у контексті користувача

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'

Однак у вашому інтерфейсі може знадобитися знати, чи показувати кнопку «показати відповіді» на кожному коментарі. При отриманні коментарів у вигляді дерева до коментарів додається властивість hasChildren, коли це застосовано.

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

Можливо шукати за хештегом за допомогою 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'

Усі параметри запиту

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

Copy

interface CommentsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** Ідентифікатор urlId (URL сторінки або ID статті), з яким пов'язані коментарі. **/
    urlId?: string
    /** Обмежити коментарі, повернуті цим користувачем. **/
    userId?: string
    /** Використовуйте це для пошуку за хештегом. Щоб отримати перетин кількох хештегів, використовуйте &hashTag=a&hashTag=b. **/
    hashTag?: string
    /** Напрямок сортування. За замовчуванням MR (Найбільш релевантний). Інші варіанти: OF (Спочатку найстаріші) та NF (Спочатку найновіші). **/
    direction?: 'MR' | 'OF' | 'NF'
    /** Попередньо обчислена пагінація: Сторінка для отримання, починаючи з 0. Передайте -1 для всіх коментарів (до 250). **/
    page?: number
    /** Гнучка пагінація: Скільки коментарів повернути? **/
    limit?: number
    /** Гнучка пагінація: Скільки дочірніх коментарів повернути для кожного батька? **/
    limitChildren?: number
    /** Гнучка пагінація: Скільки коментарів пропустити? **/
    skip?: number
    /** Гнучка пагінація: Скільки дочірніх коментарів пропустити для кожного батька? **/
    skipChildren?: number
    /** Для визначення заблокованих та позначених коментарів. **/
    contextUserId?: string
    /** Для визначення заблокованих та позначених коментарів. **/
    anonUserId?: string
    /** Для отримання дочірніх коментарів. **/
    parentId?: string
    /** Для отримання у вигляді дерева. **/
    asTree?: boolean
    /** Наскільки глибоко в дереві повертати дані? 0 — без дочірніх, 1 — лише безпосередні дочірні тощо. **/
    maxTreeDepth?: number
}

Відповідь

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

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[]
}

Корисні поради

URL ID

Ви, ймовірно, захочете використовувати API Comment з параметром urlId. Спочатку можна викликати API Pages, щоб побачити, які значення urlId доступні.

Анонімні дії

Для анонімних коментарів, ймовірно, варто передавати anonUserId під час отримання коментарів та під час позначення та блокування.

(!) Це вимога багатьох магазинів додатків, оскільки користувачі повинні мати можливість позначати створений користувачем контент, який вони бачать, навіть якщо вони не ввійшли в систему. Якщо цього не зробити, ваш додаток може бути видалений з цього магазину.

Коментарі не повертаються

Переконайтеся, що ваші коментарі схвалені і не є спамом.

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

Цей API-ендпоінт надає можливість створювати коментарі.

Типові варіанти використання: кастомні інтерфейси, інтеграції або імпорти.

Примітки:

Цей API може оновлювати віджет коментарів "live" за бажанням (це збільшує creditsCost з 1 до 2).
Якщо вказано email, цей API автоматично створить об'єкти користувачів у нашій системі.
Спроба зберегти два коментарі з різними email, але однаковим іменем користувача, призведе до помилки для другого коментаря.
Якщо ви вказуєте parentId, і дочірній коментар має notificationSentForParent зі значенням false, ми відправимо повідомлення для батьківського коментаря. Це робиться щогодини (ми групуємо повідомлення, щоб зменшити кількість відправлених електронних листів).
Якщо ви хочете надсилати вітальні листи при створенні користувачів або листи для верифікації коментарів, встановіть sendEmails в true у параметрах запиту.
Коментарі, створені через цей API, відображатимуться на сторінках Аналітики та Модерації в адмін-додатку.
Якщо налаштування увімкнено, "bad words" все ще маскуються в іменах коментаторів та в тексті коментаря.
Коментарі, створені через цей API, все ще можуть перевірятися на спам за бажанням.
Налаштування, такі як максимальна довжина коментаря, якщо вони вказані через сторінку правил кастомізації в адмін-панелі, застосовуватимуться тут.

Мінімальні дані, необхідні для відправки і відображення у віджеті коментарів, такі:

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

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

Більш реальний запит може виглядати так:

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

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 може оновлювати віджет коментарів "live" якщо бажано (це збільшує базове creditsCost з 1 до 2).
- Це може зробити міграцію коментарів між сторінками "live" (зміна urlId).
- Міграції коштують додаткові 2 кредити, оскільки сторінки попередньо обчислюються і це інтенсивно використовує CPU.
На відміну від API створення, цей API НЕ автоматично створюватиме об'єкти користувачів у нашій системі, якщо вказано email.
Коментарі, оновлені через цей API, все ще можуть перевірятися на спам за бажанням.
Конфігурація, така як максимальна довжина коментаря, якщо налаштована через сторінку адміністрування Customization Rule, застосовуватиметься тут.
Щоб дозволити користувачам оновлювати текст свого коментаря, ви можете просто вказати comment у тілі запиту. Ми згенеруємо відповідний commentHTML.
- Якщо ви зазначите і comment, і commentHTML, ми не будемо автоматично генерувати HTML.
- Якщо користувач додає згадки або хештеги у свій новий текст, вони все одно будуть оброблені так само, як у POST API.
При оновленні commenterEmail у коментарі, краще також вказати userId. В іншому випадку потрібно переконатися, що користувач з цим email належить до вашого тенанта, інакше запит не пройде.
Якщо цільовий коментар заблоковано (isLocked: true), запит відхиляється з code: 'locked'. Спочатку розблокуйте коментар, оновіть його, потім знову заблокуйте за потреби.

Мінімальний приклад 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'
	/** Чи повинен коментар відображатися "live" для користувачів, які переглядають екземпляри віджета коментарів з тим самим urlId. NOTE: Подвоює вартість в кредитах з 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' | 'locked'
    /** Додається у випадку невдачі. **/
    reason?: string
}

DELETE /api/v1/comments/:id

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

Цей ендпоінт API надає можливість видалити коментар.

Notes:

Цей API може оновлювати віджет коментарів у режимі "live", якщо потрібно (це збільшує creditsCost з 1 до 2).
Цей API видалить всі дочірні коментарі.
Якщо цільовий коментар заблоковано (isLocked: true), запит відхиляється з code: 'locked'. Спочатку розблокуйте коментар, потім видаліть його.

Приклад 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. УВАГА: Подвоює вартість у кредитах з 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' | 'locked'
    /** Надається у разі невдачі. **/
    reason?: string
}

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

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

Цей API-ендпоінт дозволяє позначити коментар для конкретного користувача.

Примітки:

Цей виклик завжди має виконуватися в контексті користувача. Користувач може бути користувачем FastComments.com, SSO-користувачем або користувачем орендаря.
Якщо встановлено поріг flag-to-hide, коментар буде автоматично приховано в реальному часі після того, як його позначать визначену кількість разів.
Після того, як він автоматично буде знятий зі схвалених (прихований) — коментар може бути повторно схвалений лише адміністратором або модератором. Зняття позначки (un-flagging) не призведе до повторного схвалення коментаря.

Приклад 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, SSO-користувачами та користувачами орендаря.

Підтримується параметр тіла commentIdsToCheck, щоб перевірити, чи інші потенційно видимі коментарі на клієнті повинні бути заблоковані/розблоковані після виконання цієї дії.

Примітки:

Цей виклик завжди має виконуватися в контексті користувача. Користувач може бути користувачем FastComments.com, SSO-користувачем або користувачем орендаря.
userId у запиті — це користувач, який виконує блокування. Наприклад: User A хоче заблокувати User B. Передайте userId=User A та id коментаря, який написав User B.
Повністю анонімні коментарі (немає id користувача, немає електронної пошти) не можна заблокувати — буде повернено помилку.

Приклад 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 Users та Tenant Users.

Він підтримує параметр тіла запиту commentIdsToCheck, щоб перевірити, чи інші потенційно видимі коментарі на клієнті слід заблокувати/розблокувати після виконання цієї дії.

Примітки:

Цей виклик завжди має виконуватися в контексті користувача. Користувач може бути FastComments.com User, SSO User або Tenant User.
Параметр userId у запиті — це користувач, який виконує розблокування. Наприклад: User A хоче розблокувати User B. Передайте userId=User A та id коментаря, який написав User B.
Повністю анонімні коментарі (без ідентифікатора користувача та без електронної пошти) не можуть бути заблоковані, і буде повернено помилку.

Приклад 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 можна отримати з кінцевої точки /definitions.
Кінцева точка /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'
    /** Included on failure. **/
    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';  
    /** Included on failure. **/
    reason?: string
    /** The updated email template. **/
    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'
    /** Included on failure. **/
    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';
    /** Included on failure. **/
    reason?: string
    /** The created template. **/
    emailTemplate?: EmailTemplate
}

POST /api/v1/email-templates/render

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

Цей API-ендпоінт дозволяє попередньо переглядати шаблони електронної пошти.

Мінімальний приклад cURL для попереднього перегляду EmailTemplate POST

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 %>."
}'

Структура запиту EmailTemplate POST

Copy

interface EmailTemplatePostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура відповіді EmailTemplate POST

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
}

Структура публікації у стрічці

A FeedPost object represents a post in a FastComments feed. A feed is a stream of posts with their own comment threads, rendered by the Feed widget. Every post has an author, optional rich content, media, and links, and can be tagged so that a feed can be filtered.

Об’єкт FeedPost представляє пост у стрічці FastComments. Стрічка — це потік постів зі своїми власними гілками коментарів, які відображаються за допомогою віджету Feed. Кожен пост має автора, необов’язковий багатий вміст, медіа та посилання, і може бути позначений тегами, щоб стрічку можна було фільтрувати.

The structure for the FeedPost object is as follows:

Структура об’єкта FeedPost виглядає наступним чином:

Структура FeedPost

Copy

interface FeedPost {
    /** READONLY **/
    _id: string
    /** READONLY **/
    tenantId: string
    title?: string
    /** Ідентифікатор користувача FastComments або SSO, який створив пост. **/
    fromUserId?: string
    /** Заповнюється з даних користувача, якщо не встановлено. **/
    fromUserDisplayName?: string | null
    /** READONLY. Заповнюється з даних користувача. **/
    fromUserAvatar?: string | null
    /** Використовується для фільтрації стрічки. **/
    tags?: string[]
    /** Вага сортування в межах стрічки. Вищі значення сортуються першими. **/
    weight?: number
    /** Пари ключ/значення довільного формату для вашого використання. **/
    meta?: Record<string, string>
    /** Очищений HTML. **/
    contentHTML?: string
    media?: FeedPostMediaItem[]
    links?: FeedPostLink[]
    /** READONLY **/
    createdAt: string
    /** READONLY. Reaction type to count. **/
    reacts?: Record<string, number>
    /** READONLY **/
    commentCount?: number | null
}
interface FeedPostMediaItem {
    title?: string
    /** Куди посилається медіа‑елемент при кліку. **/
    linkUrl?: string
    /** Один запис на кожну варіацію. Віджет вибирає найкращий варіант. **/
    sizes: FeedPostMediaItemAsset[]
}
interface FeedPostMediaItemAsset {
    w: number
    h: number
    src: string
}
interface FeedPostLink {
    /** Текст посилання, наприклад "Sign up now". **/
    text?: string
    /** Заголовок, що відображається разом з посиланням. **/
    title?: string
    /** Опис, що відображається разом з посиланням. **/
    description?: string
    url?: string
}

Notes:

Примітки:

Деякі з цих полів позначені READONLY — вони повертаються API, але не можуть бути встановлені.
Коментарі до поста є звичайними коментарями, у яких urlId має вигляд post: + _id поста. Використовуйте це значення з Comment API, щоб читати або створювати коментарі до поста.

GET /api/v1/feed-posts

Resource: FeedPost as GET /api/v1/feed-posts Credit Cost: 1

Отримує пости у стрічці, спочатку найновіші. Пагінація базується на курсорі: передайте _id останнього отриманого поста як afterId, щоб отримати наступну сторінку.

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

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

Copy

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

Структура запиту FeedPost

Copy

interface FeedPostsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** Return posts after this post id. Omit for the first page. **/
    afterId?: string
    /** Defaults to 10. Maximum 1000. **/
    limit?: number
    /** Only return posts with these tags. Repeat the parameter for more than one tag. **/
    tags?: string[]
}

Структура відповіді FeedPost

Copy

interface FeedPostsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'limit-invalid' | 'internal'
    /** Included on failure. **/
    reason?: string
    feedPosts: FeedPost[]
}

POST /api/v1/feed-posts

Resource: FeedPost as POST /api/v1/feed-posts Credit Cost: 1

Цей маршрут створює один FeedPost. Кожен пост має автора, тому fromUserId є обов’язковим і має бути ідентифікатором існуючого користувача FastComments або SSO в обліковому записі.

Приклад cURL створення FeedPost

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/feed-posts?tenantId=demo&isLive=true&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "fromUserId": "some-user-id",
    "title": "Release 2.0 is out",
    "contentHTML": "<p>Read the notes and tell us what you think.</p>",
    "tags": ["releases"],
    "links": [
        {
            "url": "https://example.com/releases/2.0",
            "title": "Release notes",
            "description": "Everything that changed in 2.0."
        }
    ]
}'

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

Copy

interface FeedPostPostQueryParams {
    tenantId: string
    API_KEY: string
    /** Надає пост у стрічки, які відкриті в браузері прямо зараз. За замовчуванням false. **/
    isLive?: boolean
    /** Запускає пост через спам‑двигун перед збереженням. За замовчуванням false. **/
    doSpamCheck?: boolean
    /** Пропускає перевірку повторюваного вмісту, яка виконується в рамках doSpamCheck. За замовчуванням false. **/
    skipDupCheck?: boolean
    /** До 256 символів. Повертається живим слухачам, щоб клієнт міг ігнорувати власне мовлення. **/
    broadcastId?: string
}
interface FeedPostPostBody {
    /** Обов’язково. Ідентифікатор користувача FastComments або SSO. **/
    fromUserId: string
    title?: string
    /** HTML. Очищено при збереженні. **/
    contentHTML?: string
    /** Перезаписує відображуване ім’я, отримане від користувача. **/
    fromUserDisplayName?: string
    tags?: string[]
    media?: FeedPostMediaItem[]
    links?: FeedPostLink[]
    meta?: Record<string, string>
}

Структура відповіді створення FeedPost

Copy

interface FeedPostPostResponse {
    status: 'success' | 'failed'
    /** Включено у випадку помилки. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-from-user-id' | 'invalid-user' | 'broadcast-id-too-long' | 'spam-blocked' | 'user-rate-limited' | 'internal'
    /** Включено у випадку помилки. **/
    reason?: string
    feedPost?: FeedPost; // Ми повертаємо повний створений пост у випадку успіху.
}

PATCH /api/v1/feed-posts/:id

Resource: FeedPost as PATCH /api/v1/feed-posts/:id Credit Cost: 1

Цей маршрут оновлює один FeedPost. Надішліть лише поля, які ви хочете змінити.

Приклад cURL для оновлення FeedPost

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/feed-posts/some-post-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Release 2.0.1 is out",
    "tags": ["releases", "hotfix"]
}'

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

Copy

interface FeedPostPatchQueryParams {
    tenantId: string
    API_KEY: string
}
/** Any writable field from the FeedPost structure. **/
type FeedPostPatchBody = Partial<Pick<FeedPost, 'title' | 'contentHTML' | 'fromUserDisplayName' | 'tags' | 'weight' | 'meta' | 'media' | 'links'>>

Структура відповіді оновлення FeedPost

Copy

interface FeedPostPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'internal'
    /** Included on failure. **/
    reason?: string
}

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

Об'єкт HashTag представляє тег, який може залишити користувач. Хештеги можуть використовуватися для зв'язування з зовнішнім вмістом або для об'єднання пов'язаних коментарів.

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

Структура 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. HashTags повертаються сторінками по 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; // Ми повертаємо повністю оновлений хештег при успіху.
}

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
}

GET /api/v1/me

Resource: Me as GET /api/v1/me Credit Cost: 1

Описує облікові дані, які роблять запит: орендар, до якого вони належать, і, для токенів доступу OAuth, користувача, який авторизував застосунок. Інтеграції використовують їх для тестування з’єднання та позначення його.

При використанні API‑ключа відповідь ідентифікує лише орендаря. При використанні токену OAuth вона також містить користувача, який здійснив авторизацію, та надані області доступу.

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

Copy

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

Структура відповіді Me

Copy

interface MeResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    tenantId: string
    tenantName: string
    /** How the request was authenticated. **/
    authType: 'api-key' | 'oauth'
    /** The scopes the credential holds. API keys hold both. **/
    scopes: ('read' | 'write')[]
    /** Only present for OAuth tokens. **/
    userId?: string
    username?: string
    email?: string
}

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

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

Існує три типи модераторів:

Користувачі-адміністратори, які мають прапорець isCommentModeratorAdmin.
Користувачі SSO з прапорцем isCommentModeratorAdmin.
Звичайні коментатори або користувачі FastComments.com, яких запрошують як модераторів.

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

Якщо ви хочете запросити користувача стати модератором через API, використайте API Moderator, створивши Moderator і inviting їх.

Якщо у користувача немає облікового запису FastComments.com, електронний лист із запрошенням допоможе їм налаштуватись. Якщо вони вже мають обліковий запис, вони отримають доступ для модерації до вашого tenant, і поле userId об'єкта Moderator буде оновлено, щоб вказувати на їхнього користувача. Ви не матимете API доступу до їхнього користувача, оскільки в цьому випадку він належить їм і управляється FastComments.com.

Якщо вам потрібне повне управління обліковим записом користувача, ми рекомендуємо або використовувати SSO, або додати їх як a Tenant User і потім додати об'єкт Moderator для відстеження їхніх статистик.

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

The structure for the Moderator object is as follows:

Структура 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 credit per 10 повернених модераторів.

Приклад cURL для модератора

Copy

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

Структура запиту для модераторів

Copy

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

Структура відповіді для модераторів

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, що вказано в параметрах запиту.
Двоє модераторів у тому ж tenant не можуть мати однаковий 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, що вказаний у параметрах запиту.
Не можна додати двох модераторів у тому самому тенанті з однаковим email.

Ми можемо створити Moderator для користувача, якого ми знаємо тільки за електронною поштою:

Приклад cURL: створення Модератора за електронною поштою

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 для користувача, який належить нашому тенанту, щоб відстежувати його статистику модерації:

Приклад cURL: створення Модератора для користувача тенанта

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"
}'

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

Copy

interface ModeratorPostQueryParams {
    tenantId: string
    API_KEY: string
}

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

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.

Примітки:

Якщо користувач із вказаною електронною поштою вже існує, йому буде надіслано запрошення модерувати коментарі вашого тенанта.
Якщо користувача з вказаною електронною поштою не існує, посилання-запрошення проведе його через процес створення облікового запису.
Термін дії запрошення закінчується через 30 days.

Ми можемо створити Moderator для користувача, про якого ми знаємо лише електронну пошту:

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

Copy

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

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

Copy

interface ModeratorDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

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

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,
    /** Якщо у вас є приватне повідомлення (DM). **/
    DirectMessage = 5,
    /** TrialLimits призначено лише для користувачів tenant. **/
    TrialLimits = 6,
    /** Якщо вас згадали за допомогою @. **/
    Mentioned = 7
}
interface Notification {
    id: string
    tenantId: string
    /** With SSO, the user id is in the format `<tenant id>:<user id>`. **/
    userId?: string
    /** When working with SSO, you only have to worry about `userId`. **/
    anonUserId?: string
    /** urlId is almost always defined. It is only optional for tenant-level notifications, which are infrequent. **/
    urlId?: string
    /** URL is cached for quick navigation to the source of the notification. **/
    url?: string
    /** Page Title is cached for quick reading of notification source. **/
    pageTitle?: string
    relatedObjectType: NotificationObjectType
    /** For example, comment id. **/
    relatedObjectId: string
    viewed: boolean
    createdAt: string // рядок дати
    type: NotificationType
    fromCommentId?: string
    fromVoteId?: string
    /** fromUserName and fromUserAvatarSrc are cached here for quick displaying of the notification. They are updated when the user is updated. **/
    fromUserName: string
    fromUserId: string
    fromUserAvatarSrc?: string
    /** Set this to true to stop getting notifications for this object. **/
    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'

Структура запиту Notifications

Copy

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

Структура відповіді Notifications

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
}

Публічний API реакцій на сторінці

Page Reacts дозволяє вашим користувачам лайкати сторінку або реагувати на неї за допомогою власного набору зображень реакцій. Віджет Page Reacts widget та віджет Floating Likes побудовані на цих кінцевих точках, і ви можете викликати їх самостійно, щоб створити власну кнопку лайка.

На відміну від решти цього посібника, кінцеві точки Page Reacts є публічними. Вони викликаються з браузерів ваших користувачів, не потребують API‑ключа і не вимагають API‑кредитів. Кожна реакція належить користувачу, який робить запит, тому користувач може додавати або видаляти лише свої реакції.

Існує два набори кінцевих точок:

/page-reacts/v1/likes/:tenantId — один «лайк» на користувача на сторінку. Використовуйте їх для кнопки лайка.
/page-reacts/v2/:tenantId — кілька реакцій на сторінку, кожна ідентифікується коротким id, який ви обираєте (наприклад heart або laugh).

Обидва також доступні в наших SDK як частина PublicApi, наприклад getV1PageLikes, createV1PageReact та deleteV1PageReact у JavaScript SDK.

Визначення користувача

Реакції прив'язані до користувача, який робить запит:

SSO користувачі: передайте параметр запиту sso, встановлений у URI‑закодований JSON того ж SSO‑об’єкта, який ви передаєте віджету коментарів. Дивіться SSO.
Анонімні користувачі: коли немає параметра sso і немає входу в FastComments, сервер призначає браузеру анонімний ідентифікатор, збережений у cookie сесії FastComments. Надсилайте запити з credentials: 'include', щоб cookie зберігався між запитами. Браузери, які блокують сторонні cookie, не збережуть анонімний ідентифікатор, тому використовуйте SSO, коли кожного користувача потрібно надійно розпізнавати.

Ідентифікатор urlId

urlId ідентифікує сторінку, так само, як і для коментарів. Використовуйте той самий urlId, який ви передаєте віджету коментарів, щоб лайки та коментарі підраховувалися на одній і тій же сторінці. Не забудьте закодувати його у URI.

Приклад кнопки лайка

Copy

const tenantId = 'demo';
const urlId = 'https://example.com/my-article';
// Optional, for SSO users. The same object you give the comment widget's "sso" option.
const sso = null;
function likesUrl() {
    let url = `https://fastcomments.com/page-reacts/v1/likes/${tenantId}?urlId=${encodeURIComponent(urlId)}`;
    if (sso) {
        url += '&sso=' + encodeURIComponent(JSON.stringify(sso));
    }
    return url;
}
async function getLikes() {
    const response = await fetch(likesUrl(), {credentials: 'include'});
    return response.json(); // {status, likeCount, didLike, commentCount, urlIdWS}
}
async function like() {
    await fetch(likesUrl(), {method: 'POST', credentials: 'include'});
}
async function unlike() {
    await fetch(likesUrl(), {method: 'DELETE', credentials: 'include'});
}

GET /page-reacts/v1/likes/:tenantId

Resource: Page Likes as GET /page-reacts/v1/likes/:tenantId Credit Cost: 0

Повертає кількість лайків на сторінці та чи поточний користувач поставив лайк. Сторінки, які ще не існують, повертають likeCount рівний 0.

Приклад cURL запиту для лайків сторінки

Copy

curl --request GET \
  --url 'https://fastcomments.com/page-reacts/v1/likes/demo?urlId=example-id-or-url'

Структура запиту лайків сторінки

Copy

interface PageLikesRequestQueryParams {
    urlId: string
    /** URI‑закодований JSON вашого об’єкта SSO. Пропустіть для анонімних користувачів. **/
    sso?: string
}

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

Copy

interface PageLikesResponse {
    status: 'success' | 'failed'
    /** Включено у випадку помилки. **/
    code?: string
    /** Включено у випадку помилки. **/
    reason?: string
    likeCount: number
    /** Чи користувач, який робить запит, поставив лайк сторінці. **/
    didLike: boolean
    /** Кількість коментарів верхнього рівня на сторінці. **/
    commentCount: number
    /** Ідентифікатор, який використовується для підписки на живі оновлення цієї сторінки. **/
    urlIdWS: string
}

POST /page-reacts/v1/likes/:tenantId

Resource: Page Likes as POST /page-reacts/v1/likes/:tenantId Credit Cost: 0

Лайкає сторінку від імені поточного користувача. Кожен користувач може лайкнути сторінку лише один раз: повторне лайкання успішне з кодом already-liked і не змінює лічильник.

Сторінка створюється, якщо ще не існує. Передайте title, щоб встановити або оновити заголовок сторінки.

Приклад cURL для лайку сторінки

Copy

curl --request POST \
  --url 'https://fastcomments.com/page-reacts/v1/likes/demo?urlId=example-id-or-url&title=My%20Article'

Структура запиту лайку сторінки

Copy

interface PageLikeRequestQueryParams {
    urlId: string
    /** Встановлює заголовок сторінки. **/
    title?: string
    /** URI‑закодований JSON вашого SSO‑об’єкта. Пропустіть для анонімних користувачів. **/
    sso?: string
}

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

Copy

interface PageLikeResponse {
    status: 'success' | 'failed'
    /** 'already-liked' коли користувач вже лайкнув сторінку. Інакше включається при помилці. **/
    code?: 'already-liked' | string
    /** Включається при помилці. **/
    reason?: string
}

DELETE /page-reacts/v1/likes/:tenantId

Resource: Page Likes as DELETE /page-reacts/v1/likes/:tenantId Credit Cost: 0

Видаляє лайк поточного користувача зі сторінки. Якщо користувач не лайкнув сторінку, запит успішно завершується з кодом not-liked і не змінює лічильник.

Приклад cURL для скасування лайка сторінки

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/page-reacts/v1/likes/demo?urlId=example-id-or-url'

Структура запиту скасування лайка сторінки

Copy

interface PageUnlikeRequestQueryParams {
    urlId: string
    /** URI закодований у JSON вашого об’єкта SSO. Пропустіть для анонімних користувачів. **/
    sso?: string
}

Структура відповіді скасування лайка сторінки

Copy

interface PageUnlikeResponse {
    status: 'success' | 'failed'
    /** 'not-liked' коли користувач не лайкнув сторінку. Інакше включається у випадку помилки. **/
    code?: 'not-liked' | string
    /** Включається у випадку помилки. **/
    reason?: string
}

GET /page-reacts/v2/:tenantId

Resource: Page Reacts as GET /page-reacts/v2/:tenantId Credit Cost: 0

Повертає кількість кожної реакції на сторінці та які реакції додав поточний користувач.

Приклад cURL для Page Reacts

Copy

curl --request GET \
  --url 'https://fastcomments.com/page-reacts/v2/demo?urlId=example-id-or-url'

Структура запиту Page Reacts

Copy

interface PageReactsRequestQueryParams {
    urlId: string
    /** URI закодований JSON вашого об’єкта SSO. Пропустіть для анонімних користувачів. **/
    sso?: string
}

Структура відповіді Page Reacts

Copy

interface PageReactsResponse {
    status: 'success' | 'failed'
    /** Включено у випадку помилки. **/
    code?: string
    /** Включено у випадку помилки. **/
    reason?: string
    /** Кількість для кожного id реакції, наприклад {"heart": 12, "laugh": 3}. Не встановлюється, коли на сторінці немає реакцій. **/
    counts?: Record<string, number>
    /** ID реакцій, які додав користувач, що робить запит. Не встановлюється, якщо жодної не додано. **/
    reactedIds?: string[]
}

GET /page-reacts/v2/:tenantId/list

Resource: Page React Users as GET /page-reacts/v2/:tenantId/list Credit Cost: 0

Повертає імена користувачів, які додали реакцію до сторінки, відсортовані в алфавітному порядку. Перевіряється до 100 реакцій, а анонімні користувачі не включаються.

Приклад cURL запиту Page React Users

Copy

curl --request GET \
  --url 'https://fastcomments.com/page-reacts/v2/demo/list?urlId=example-id-or-url&id=heart'

Структура запиту Page React Users

Copy

interface PageReactUsersRequestQueryParams {
    urlId: string
    /** The reaction id. **/
    id: string
    /** URI encoded JSON of your SSO object. Omit for anonymous users. **/
    sso?: string
}

Структура відповіді Page React Users

Copy

interface PageReactUsersResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: string
    /** Included on failure. **/
    reason?: string
    userNames: string[]
}

POST /page-reacts/v2/:tenantId

Resource: Page Reacts as POST /page-reacts/v2/:tenantId Credit Cost: 0

Додає реакцію до сторінки від імені поточного користувача. Користувач може додати кожен ідентифікатор реакції лише один раз: повторне додавання успішне з кодом already-reacted і не змінює лічильник. Користувач може додати кілька різних реакцій до однієї сторінки.

Ідентифікатори реакцій вибираються вами і можуть мати до 36 символів. Сторінка створюється, якщо ще не існує. Передайте title, щоб встановити або оновити заголовок сторінки.

Приклад cURL запиту реакції на сторінку

Copy

curl --request POST \
  --url 'https://fastcomments.com/page-reacts/v2/demo?urlId=example-id-or-url&id=heart'

Структура запиту реакції на сторінку

Copy

interface PageReactRequestQueryParams {
    urlId: string
    /** The reaction id, up to 36 characters. **/
    id: string
    /** Sets the page's title. **/
    title?: string
    /** URI encoded JSON of your SSO object. Omit for anonymous users. **/
    sso?: string
}

Структура відповіді реакції на сторінку

Copy

interface PageReactResponse {
    status: 'success' | 'failed'
    /** 'already-reacted' when the user had already added this reaction. 'react-id-too-long' (HTTP 422) when the id is over 36 characters. Otherwise included on failure. **/
    code?: 'already-reacted' | 'react-id-too-long' | string
    /** Included on failure. **/
    reason?: string
}

DELETE /page-reacts/v2/:tenantId

Resource: Page Reacts as DELETE /page-reacts/v2/:tenantId Credit Cost: 0

Видаляє одну з реакцій поточного користувача зі сторінки. Якщо користувач не додав цю реакцію, запит успішно завершується з кодом no-react і не змінює лічильник.

Приклад cURL для видалення реакції на сторінці

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/page-reacts/v2/demo?urlId=example-id-or-url&id=heart'

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

Copy

interface PageReactDeleteRequestQueryParams {
    urlId: string
    /** Ідентифікатор реакції. **/
    id: string
    /** URI закодований JSON вашого SSO об’єкта. Пропустіть для анонімних користувачів. **/
    sso?: string
}

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

Copy

interface PageReactDeleteResponse {
    status: 'success' | 'failed'
    /** 'no-react' коли користувач не додав цю реакцію. Інакше включається при помилці. **/
    code?: 'no-react' | string
    /** Включено при помилці. **/
    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-запиту для Pages

Copy

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

Структура запиту Pages

Copy

interface PagesRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Структура відповіді Pages

Copy

interface PagesResponse {
    status: 'success' | 'failed'
    /** Включається у разі помилки. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Включається у разі помилки. **/
    reason?: string
    pages: Page[]
}

Корисна порада

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

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'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id'
    /** Included on failure. **/
    reason?: string
    page?: Page[] | null
}

Корисна порада

Пам'ятайте кодувати значення, такі як urlId, у форматі URI.

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 оновлюються автоматично. Ці параметри — підрахунки та атрибути заголовка. Підрахунки не можна оновити через API, оскільки вони є обчислюваними значеннями. Заголовок сторінки title можна встановити через API, але він буде перезаписаний, якщо віджет коментарів використовується на сторінці з тим самим urlId та іншим заголовком сторінки.

POST /api/v1/pages

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

Ця кінцева точка API надає можливість створювати сторінки.

Одним із поширених випадків використання є контроль доступу.

Примітки:

Якщо ви залишали коментар у гілці коментарів або викликали API для створення Comment, ви вже створили об'єкт Page! Ви можете спробувати отримати його через маршрут Page /by-url-id, передавши той самий 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 Poll прикріплюється до коментаря, а не є окремим об’єктом. Він створюється разом з коментарем
(див. POST /api/v1/comments), або додається до існуючого коментаря пізніше за допомогою PUT /api/v1/polls/:commentId.

Кількість голосів зберігається безпосередньо в опитуванні, тому читання опитування дає вам результати без необхідності підсумовувати їх. Окремі голоси, що стоять за цими підрахунками, є об’єктами PollVote.

Кожен варіант має id, який генерується під час створення опитування. Цей id використовується для подачі голосу, зміни мітки варіанту та збереження варіанту (разом з його голосами) під час PUT опитування з доданими або видаленими варіантами. Це єдиний безпечний спосіб посилання на варіант — ніколи не використовуйте його позицію у списку.

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

Copy

interface CommentPollOption {
    id: string
    label: string
    votes: number
}
interface CommentPoll {
    question: string
    options: CommentPollOption[]
    totalVotes: number
    /** When set and in the past, the poll is closed and no longer accepts votes. **/
    closesAt?: string | null
    /** 0 anonymous (the default), 1 admins and moderators, 2 everyone. Absent means anonymous. **/
    privacy?: 0 | 1 | 2 | null
    /** When true, the counts are hidden from anyone who has not voted yet. Absent means false. **/
    requireVoteToSeeResults?: boolean | null
}

Обмеження

Питання є обов’язковим і має максимум 200 символів.
Опитування має від 2 до 10 варіантів.
Мітка варіанту є обов’язковою, має максимум 100 символів і повинна бути унікальною в межах опитування (без урахування регістру).
closesAt має бути в майбутньому під час створення опитування. Щоб закрити опитування негайно, виконайте PATCH з датою в минулому.

Налаштування сайту

Опитування підкоряються конфігурації вашого сайту, яку можна змінити під Customize Widget:

Опитування мають бути ввімкнені, перш ніж можна створити опитування, інакше API відповість polls-disabled.
Голосування може бути обмежене лише зареєстрованими користувачами; у цьому випадку голос, надісланий лише з anonUserId, буде відхилений з помилкою poll-login-required.

GET /api/v1/polls/:commentId

Resource: Poll as GET /api/v1/polls/:commentId Credit Cost: 1

Читає опитування, прикріплене до коментаря, з його поточними підрахунками голосів.

Опитування також повертаються разом з самим коментарем через API коментарів, тому використовуйте це, коли вам потрібні лише результати, а не весь коментар.

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

Copy

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

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

Copy

interface PollGetQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface PollGetResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'poll-not-found'
    /** Included on failure. **/
    reason?: string
    poll: CommentPoll
}

Коментар без опитування, видалений коментар та ідентифікатор коментаря, якого не існує, всі відповідають однаково, з poll-not-found.

PUT /api/v1/polls/:commentId

Resource: Poll as PUT /api/v1/polls/:commentId Credit Cost: 1

Прикріплює опитування до існуючого коментаря, або встановлює повний стан опитування, яке вже існує.

Тіло є повним опитуванням, і передані вами варіанти стають варіантами опитування у зазначеному порядку. Кожен варіант співставляється за його id:

Варіант, надісланий з id існуючого варіанту, зберігає цей варіант і його голоси. Його мітка та позиція оновлюються згідно з надісланим.
Варіант, надісланий без id, додається без голосів.
Існуючий варіант, який ви пропускаєте, видаляється разом з голосами, відданими за нього. totalVotes зменшується на ту ж саму кількість.

Отже, щоб додати варіант, надішліть поточні варіанти з їхніми id та новий без id. Щоб видалити варіант, надішліть список без нього. Id варіантів містяться в опитуванні, яке повертає GET /api/v1/polls/:commentId.

Надсилання без жодних id замінює всі варіанти та видаляє всі вже віддані голоси в опитуванні. Якщо в опитуванні є голоси, це вимагає replaceVotes=true, а без цього API відповідає replace-votes-required.

Інші поля також замінюються: пропуск closesAt, privacy або requireVoteToSeeResults скидає їх до значення за замовчуванням. Щоб змінити лише одне поле і залишити інші без змін, використовуйте PATCH /api/v1/polls/:commentId.

Приклад cURL запиту Poll Put

Copy

curl --request PUT \
  --url 'https://fastcomments.com/api/v1/polls/comment-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"question": "Which release should we cut first?",
	"options": [
		{"id": "existing-option-id", "label": "The bugfix release"},
		{"label": "The feature release"}
	],
	"closesAt": "2026-12-31T00:00:00.000Z"
}'

Структура запиту Poll Put

Copy

interface PollPutQueryParams {
    tenantId: string
    API_KEY: string
    /** Required to keep none of the existing option ids when the poll has votes, since that deletes them all. **/
    replaceVotes?: boolean
}
interface PollPutOption {
    /** The id of an existing option, to keep it and its votes. Omit to add a new option. **/
    id?: string | null
    label: string
}
interface PollPutBody {
    question: string
    /** The complete, ordered list. Existing options left out are removed with their votes. **/
    options: PollPutOption[]
    /** Must be in the future when the comment has no poll yet. Omit for a poll that stays open. **/
    closesAt?: string | null
    /** 0 anonymous (the default), 1 admins and moderators, 2 everyone. **/
    privacy?: 0 | 1 | 2 | null
    requireVoteToSeeResults?: boolean | null
}

Структура відповіді Poll Put

Copy

interface PollPutResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'polls-disabled' | 'poll-invalid' | 'replace-votes-required' | 'poll-privacy-locked' | 'locked'
    /** Included on failure. **/
    reason?: string
    poll: CommentPoll
}

Інші нотатки

id, який відсутній в опитуванні, або той самий id, вказаний двічі, призводить до помилки poll-invalid. Коментар без опитування ще не має id варіантів, тому кожен варіант, який надсилається, повинен мати пропущений id.
Приватність опитування можна обмежити, але не розширити після того, як у ньому є голоси.
Цей API дотримується налаштувань вашого сайту. Якщо опитування не ввімкнені для сайту або сторінки, виникає помилка polls-disabled.
Заблокований коментар не може мати змінене опитування, і повертає помилку locked.
Підключені віджети оновлюються в режимі реального часу, тому глядачі бачать нове опитування без перезавантаження.

PATCH /api/v1/polls/:commentId

Resource: Poll as PATCH /api/v1/polls/:commentId Credit Cost: 1

Редагує опитування, не порушуючи його голосів. Використовуйте це, щоб виправити помилку в питанні або варіанті, щоб закрити або відкрити опитування, або змінити, хто може бачити, хто проголосував.

Опції ідентифікуються за їх id, і PATCH перейменовує ті, які ви вказали. Щоб додати, видалити або змінити порядок опцій, надішліть повний список опцій до PUT /api/v1/polls/:commentId: опції, які ви надсилаєте з їх id, зберігають їх голоси.

Кожне поле є необов’язковим, але має бути вказано хоча б одне.

Приклад cURL для оновлення опитування

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/polls/comment-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"question": "Which release should we cut first?",
	"options": [{"id": "the-option-id", "label": "The bugfix release"}]
}'

Приклад cURL для негайного закриття опитування

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/polls/comment-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"closesAt": "2020-01-01T00:00:00.000Z"
}'

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

Copy

interface PollPatchQueryParams {
    tenantId: string
    API_KEY: string
}
interface PollPatchBody {
    question?: string | null
    /** Relabels existing options. Every id given must already be on the poll. **/
    options?: { id: string, label: string }[] | null
    /** A date in the past closes the poll now. null reopens a closed poll. **/
    closesAt?: string | null
    /** 0 anonymous, 1 admins and moderators, 2 everyone. **/
    privacy?: 0 | 1 | 2 | null
    requireVoteToSeeResults?: boolean | null
}

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

Copy

interface PollPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'poll-not-found' | 'poll-invalid' | 'poll-privacy-locked' | 'locked'
    /** Included on failure. **/
    reason?: string
    poll: CommentPoll
}

Інші нотатки

Назва id опції, якої немає в опитуванні, призводить до помилки poll-invalid, а не просто нічого не робить.
Мітки повинні залишатися унікальними в межах опитування, враховуючи опції, які ви не змінюєте.
На відміну від створення опитування, closesAt може бути в минулому — це спосіб негайно закрити опитування.
Приватність опитування можна звузити, але не розширити після того, як у ньому є голоси.
Заблокований коментар не може мати змінене опитування і повертає помилку locked.

DELETE /api/v1/polls/:commentId

Resource: Poll as DELETE /api/v1/polls/:commentId Credit Cost: 1

Видаляє опитування зі свого коментаря разом із усіма голосами, відданими за нього. Сам коментар залишається без змін.

Видалення коментаря також видаляє його опитування та голоси, тому це потрібно лише тоді, коли ви хочете залишити коментар.

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

Copy

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

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

Copy

interface PollDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface PollDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'poll-not-found'
    /** Included on failure. **/
    reason?: string
}

Структура голосу в опитуванні

A PollVote — це відповідь однієї особи на опитування. Підрахунки, що показуються безпосередньо в опитуванні, синхронізовані з цими даними, тому вони потрібні лише тоді, коли ви хочете знати хто за що проголосував, а не загальні підсумки.

У виборця може бути не більше одного голосу в одному опитуванні. Повторне голосування переміщує його існуючий голос до нової опції замість додавання другого, а updatedAt фіксує, коли це сталося.

voterId — це userId, коли виборець був увійшов, і anonUserId в іншому випадку.

Структура PollVote

Copy

interface PollVote {
    id: string
    tenantId: string
    commentId: string
    urlId: string
    /** userId, коли виборець був увійшов, інакше anonUserId. **/
    voterId: string
    optionId: string
    createdAt: string
    /** Коли виборець востаннє перемістив свій голос до іншої опції. **/
    updatedAt?: string
}

Приватність

Налаштування privacy опитування застосовується до цього API так само, як і у віджеті коментарів:

Anonymous (за замовчуванням): ніхто не може бачити, як хтось проголосував, тому голоси не можуть бути прочитані. GET /api/v1/poll-votes та GET /api/v1/poll-votes/:id відповідають poll-anonymous. Підрахунки опитування все ще доступні через GET /api/v1/polls/:commentId.
Admins and moderators: ваш API‑ключ належить адміністратору вашого сайту, тому він може читати голоси.
Everyone: голоси можна читати.

Приватність опитування можна звузити, але не розширити, після того як у ньому з'являться голоси.

GET /api/v1/poll-votes

Resource: PollVote as GET /api/v1/poll-votes Credit Cost: 1

Перелічує окремі голоси, що стоять за підрахунками одного опитування, у хронологічному порядку (спочатку найстаріші). Один кредит за кожні 100 повернутих голосів.

Опитування належить коментарю, тому голоси читаються по одному опитуванню за раз, і commentId є обов’язковим. Додатково можна уточнити за допомогою voterId, щоб перевірити, як проголосувала конкретна особа, або за допомогою optionId, щоб отримати список усіх, хто вибрав певний варіант.

За один виклик повертається максимум 1000 голосів. Використовуйте skip, щоб посторінково отримувати більше.

Налаштування privacy опитування дотримується: голоси в анонімному опитуванні не можуть бути прочитані, і запит завершується помилкою poll-anonymous. Дивіться структуру PollVote для деталей.

Приклад cURL запиту PollVotes Get

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/poll-votes?tenantId=demo&API_KEY=DEMO_API_SECRET&commentId=comment-id'

Структура запиту PollVotes Get

Copy

interface PollVotesGetQueryParams {
    tenantId: string
    API_KEY: string
    commentId: string
    voterId?: string
    optionId?: string
    skip?: number
}

Структура відповіді PollVotes Get

Copy

interface PollVotesGetResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-comment-id' | 'poll-not-found' | 'poll-anonymous'
    /** Included on failure. **/
    reason?: string
    pollVotes: PollVote[]
}

Підрахунок голосів за варіантом

Ви не повинні підсумовувати їх, щоб отримати результати — опитування містить власні підрахунки. Замість цього прочитайте опитування за допомогою GET /api/v1/polls/:commentId, і використовуйте цей API, коли потрібно знати, хто проголосував.

Кожне опитування на сторінці

Списку голосів по всій сторінці не існує. Щоб отримати звіт за всю сторінку, отримайте її коментарі за допомогою GET /api/v1/comments, який повертає опитування кожного коментаря та їх підрахунки, а потім прочитайте голоси для опитувань, які вас цікавлять.

GET /api/v1/poll-votes/:id

Resource: PollVote as GET /api/v1/poll-votes/:id Credit Cost: 1

Читає один голос опитування за його ідентифікатором.

Голос в анонімному опитуванні не може бути прочитаний, і запит завершується помилкою poll-anonymous. Дивіться структуру PollVote, щоб дізнатися, як застосовується налаштування privacy опитування.

Приклад cURL запиту PollVote Get

Copy

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

Структура запиту PollVote Get

Copy

interface PollVoteGetQueryParams {
    tenantId: string
    API_KEY: string
}

Структура відповіді PollVote Get

Copy

interface PollVoteGetResponse {
    status: 'success' | 'failed'
    /** Включено у випадку помилки. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'not-found' | 'poll-not-found' | 'poll-anonymous'
    /** Включено у випадку помилки. **/
    reason?: string
    pollVote: PollVote
}

POST /api/v1/poll-votes

Resource: PollVote as POST /api/v1/poll-votes Credit Cost: 1

Записує голос у опитуванні.

У виборця може бути не більше одного голосу в одному опитуванні. Виклик цього знову для того самого виборця переміщує його голос до нової опції замість додавання другого, а голосування за опцію, яку він вже обрав, нічого не робить.

Відповідь включає опитування, тому ви отримуєте оновлені підрахунки без другого запиту.

Приклад cURL створення PollVote

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/poll-votes?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"commentId": "comment-id",
	"optionId": "the-option-id",
	"userId": "user-id"
}'

Приклад cURL створення анонімного PollVote

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/poll-votes?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"commentId": "comment-id",
	"optionId": "the-option-id",
	"anonUserId": "some-randomly-generated-identifier",
	"ip": "203.0.113.4"
}'

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

Copy

interface PollVoteCreateQueryParams {
    tenantId: string
    API_KEY: string
}
interface PollVoteCreateBody {
    commentId: string
    optionId: string
    /** Один з userId або anonUserId є обов’язковим. **/
    userId?: string
    anonUserId?: string
    /** IP кінцевого користувача, використовується для анонімного обмеження швидкості. За замовчуванням — IP виклику. **/
    ip?: string
}

Структура відповіді створення PollVote

Copy

interface PollVoteCreateResponse {
    status: 'success' | 'failed'
    /** Включено у випадку помилки. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-comment-id' | 'missing-user-id' | 'invalid-user' | 'unauthorized' | 'poll-not-found' | 'poll-invalid-option' | 'poll-closed' | 'poll-login-required' | 'rate-limited'
    /** Включено у випадку помилки. **/
    reason?: string
    pollVote: PollVote
    /** Опитування з оновленими підрахунками. **/
    poll: CommentPoll
}

Анонімні голоси

Встановіть anonUserId замість userId, щоб записати голос для користувача, який не ввійшов у систему. Цей ідентифікатор не повинен відповідати жодному користувачу — він лише ідентифікує сесію, тому одна і та ж особа не рахується двічі.

Анонімне голосування має бути ввімкнене для вашого сайту. Якщо голосування обмежене лише зареєстрованими користувачами, голос з лише anonUserId завершиться помилкою poll-login-required.

Анонімні голоси також підлягають обмеженню швидкості за IP для кожного опитування, щоб запобігти заповненню опитування однією особою шляхом очищення їхньої сесії. Надішліть ip кінцевого користувача, щоб обмеження застосовувалося до нього, а не до вашого сервера.

Інші примітки

userId має бути користувачем, який існує на вашому сайті. Голоси для користувача, що належить іншому сайту, відхиляються.
Голосування в закритому опитуванні завершується помилкою poll-closed.
Цей API оновлює підрахунки в опитуванні та в реальному часі передає їх підключеним віджетам.

DELETE /api/v1/poll-votes/:id

Resource: PollVote as DELETE /api/v1/poll-votes/:id Credit Cost: 1

Відкликає голос. Опція, на яку був відданий голос, повертає свій лічильник, і виборець може проголосувати знову.

Приклад cURL запиту для видалення PollVote

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/poll-votes/my-id?tenantId=demo&API_KEY=DEMO_API_SECRET'

Структура запиту видалення PollVote

Copy

interface PollVoteDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Структура відповіді на видалення PollVote

Copy

interface PollVoteDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'poll-not-found'
    /** Included on failure. **/
    reason?: string
    /** The poll with its updated counts. **/
    poll: CommentPoll
}

Інші примітки

Видалення того самого голосу двічі відповідає not-found під час другого запиту, і лічильники залишаються без змін.
Якщо опитування було замінено після того, як був відданий голос, голос видаляється, але лічильники не змінюються, оскільки заміна починається з нуля.

Структура події очікуючого вебхука

Об'єкт PendingWebhookEvent представляє подію вебхука, яка знаходиться в черзі та очікує виконання.

PendingWebhookEvent об'єкти створюються автоматично і не можуть бути створені вручну через API. Їх термін дії також закінчується через один рік. Їх можна видалити, що видаляє завдання з черги.

Існують різні типи подій — перевіряйте eventType (OutboundSyncEventType) і type (OutboundSyncType).

Поширений випадок використання цього API — реалізація власного моніторингу. Можливо, ви захочете періодично викликати ендпоінт /count щоб опитувати кількість невиконаних завдань за заданими фільтрами.

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

Структура 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
    /** Остання помилка, яка сталася. Цей тип не має строгої типізації і є "дампом" того, що трапилось. Зазвичай містить об'єкт зі статусним кодом, тілом і мапою заголовків. **/
    lastError: object | null
}

GET /api/v1/pending-webhook-events

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

Цей маршрут повертає список очікуваних подій вебхуків у параметрі 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 endpoint

Приклад cURL запиту для PendingWebhookEvent Count

Copy

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

Структура запиту PendingWebhookEvent Count

Copy

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

Структура відповіді PendingWebhookEvent Count

Copy

interface PendingWebhookEventsCountResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    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.

Приклад cURL (DELETE PendingWebhookEvent)

Copy

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

Структура запиту для видалення PendingWebhookEvent

Copy

interface PendingWebhookEventDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

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

The structure for the SSOUser object is as follows:

Структура 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-користувачі з цим прапором тарифікуються як SSO-адміністратори (окремо від звичайних SSO-користувачів)
    isAdminAdmin?: boolean // Права адміністратора - SSO-користувачі з цим прапором тарифікуються як SSO-адміністратори (окремо від звичайних SSO-користувачів)
    isCommentModeratorAdmin?: boolean // Права модератора - SSO-користувачі з цим прапором тарифікуються як SSO-модератори (окремо від звичайних SSO-користувачів)
    /** Якщо null, контроль доступу не буде застосований до користувача. Якщо порожній список, цей користувач не зможе бачити жодних сторінок або використовувати @mention інших користувачів. **/
    groupIds?: string[] | null
    createdFromSimpleSSO?: boolean
    /** Не дозволяти іншим користувачам бачити активність цього користувача, включно з коментарями, у його профілі. За замовчуванням true для забезпечення захищених профілів. **/
    isProfileActivityPrivate?: boolean
    /** Не дозволяти іншим користувачам залишати коментарі в профілі цього користувача або бачити наявні коментарі профілю. За замовчуванням false. **/
    isProfileCommentsPrivate?: boolean
    /** Не дозволяти іншим користувачам надсилати цьому користувачу приватні повідомлення. За замовчуванням false. **/
    isProfileDMDisabled?: boolean
    karma?: number
    /** Необов'язкова конфігурація значків користувача. **/
    badgeConfig?: {
        /** Масив ID значків для призначення користувачу. Обмежено 30 значками. Порядок зберігається. Це глобальні значки, видимі на всіх сторінках. **/
        badgeIds: string[]
        /** Масив ID значків, обмежених поточною сторінкою (urlId). Ці значки відображаються лише на сторінці, де вони були призначені. **/
        pageBadgeIds?: string[]
        /** Якщо true, замінює всі існуючі відображувані значки на надані. Глобальні та сторінково-обмежені значки переоприділяються незалежно. Якщо false, додає до наявних значків. **/
        override?: boolean
        /** Якщо true, оновлює властивості відображення значків згідно з конфігурацією орендаря. **/
        update?: boolean
    }
}

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

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

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

Важливо: Щоб запобігти подвійній оплаті, система автоматично видаляє дублікати SSO-користувачів у порівнянні зі звичайними користувачами орендаря та модераторами за адресою електронної пошти. Якщо SSO-користувач має ту ж саму електронну пошту, що й звичайний користувач орендаря або модератор, за нього не буде стягнено плату двічі.

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

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

@Mentions

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

Підписки

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

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

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

Значки

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

badgeIds - Масив ID значків для призначення користувачу. Це глобальні значки, видимі на всіх сторінках. Повинні бути дійсними ID значків, створеними у вашому обліковому записі FastComments. Обмежено 30 значками.
pageBadgeIds - Необов'язковий масив ID значків, обмежених поточною сторінкою (urlId). Ці значки відображаються лише на сторінці, де вони були призначені. Різні сторінки можуть мати різні сторінково-обмежені значки для одного й того ж користувача.
override - Якщо true, всі існуючі відображувані значки будуть замінені на надані. Глобальні та сторінково-обмежені значки переоприділяються незалежно — переоприділення глобальних значків не впливає на сторінково-обмежені, і навпаки. Якщо false або не вказано, надані значки будуть додані до наявних.
update - Якщо true, властивості відображення значків будуть оновлюватися з конфігурації орендаря щоразу, коли користувач входить в систему.

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 за електронною поштою

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. Зауважте, що якщо це true:

Усі коментарі користувача будуть видалені в режимі live.
Всі 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 для видалення 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 objects are created when a user clicks the notification bell in the comment widget and clicks "Підписатися на цю сторінку".

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

Наявність об'єкта Subscription призводить до створення об'єктів Notification і надсилання електронних листів, коли на корені пов'язаної сторінки, для якої призначена підписка, з'являються нові коментарі. Надсилання електронних листів залежить від типу користувача. Для звичайних користувачів це залежить від optedInNotifications. Для SSO-користувачів це залежить від optedInSubscriptionNotifications. Зверніть увагу, що деякі застосунки можуть не мати поняття веб-доступної сторінки; у такому випадку просто встановіть urlId в id елемента, на який ви підписуєтесь (те ж значення 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'

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

Copy

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

Структура відповіді для підписок

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-запиту для створення підписки

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!"
}'

Структура POST-запиту підписки

Copy

interface SubscriptionPostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура відповіді 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 Search

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
    /** Based on UTC. **/
    yearNumber?: number
    /** Zero-based. Based on UTC. **/
    monthNumber?: number
    /** One-based. Based on UTC. **/
    dayNumber?: number
}

Структура відповіді TenantDailyUsage

Copy

interface TenantDailyUsageResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
    tenantDailyUsages: TenantDailyUsage[]
}

Структура орендаря

Tenant визначає клієнта FastComments.com. Вони можуть бути створені через API орендарями з доступом до white labeling. White labeled tenants не можуть створювати інших white labeled tenants (дозволено тільки один рівень вкладеності).

Структура об'єкта 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; // 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 символів. Значення не можуть бути довшими за 2000 символів. **/
    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, ми можемо construct a JSON object with this key/value pair and then URI encode it as a query param to filter:

Приклад 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 у вашому пакеті.
Ви повинні вказати параметр запиту 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-запиту PATCH для Tenant

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.

Існують такі обмеження щодо видалення тенантів:

Тенант має належати вам або бути white-label тенантом, яким ви керуєте.
Параметр запиту sure має бути встановлений у true.

Приклад cURL для видалення тенанта

Copy

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

Структура запиту для видалення тенанта

Copy

interface TenantDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

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

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
}

Структура пакету орендаря

The TenantPackage визначає інформацію про пакет, доступний для Tenant. У одного tenant може бути багато доступних пакетів, але лише один використовується в певний момент часу.

З Tenant не можна користуватися жодними продуктами, поки його packageId не вказує на дійсний TenantPackage.

Існує два типи об'єктів TenantPackage:

Пакети з фіксованими тарифами - де hasFlexPricing має значення false.
Гнучке ціноутворення - де hasFlexPricing має значення true.

У обох випадках ліміти визначаються для облікового запису, що використовує пакет, проте у випадку Flex орендарю нараховується базова плата плюс оплата за фактичне використання, яка задається параметрами flex*.

У tenant може бути кілька tenant пакетів, і він може самостійно змінювати активний пакет на Сторінці платіжної інформації.

Якщо ви будете самостійно обробляти білінг для tenant-ів, вам все одно потрібно визначити пакет для кожного tenant, щоб задати їхні ліміти. Просто встановіть 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.

Вартість залежить від кількості повернених tenant packages і становить 1 credit per 10 tenant packages.

Приклад 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
    /** Кількість tenant packages, які потрібно пропустити для пагінації. **/
    skip?: number
}

Структура відповіді TenantPackage

Copy

interface TenantPackagesResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    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 - Can be null.
- yearlyCostUSD - Can be 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 має бути «меншим» за батьківський тенант. Наприклад, всі параметри max* мають мати менші значення, ніж у батьківського тенанта.
Тенант із white-label може мати максимум п'ять пакетів.
Створювати TenantPackage можуть лише тенанти з доступом до white-label.
Ви не можете додавати пакети до власного тенанта. :)

Ми можемо створити 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 для PATCH TenantPackage

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",
}'

Структура запиту PATCH TenantPackage

Copy

interface TenantPackagePatchQueryParams {
    tenantId: string
    API_KEY: string
}

Структура відповіді PATCH TenantPackage

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, який використовується (у орендаря поле 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
}

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

The TenantUser визначає User, яким управляє конкретний тенант. Їхній обліковий запис повністю контролюється тим тенантом, з яким він пов'язаний, і обліковий запис може бути оновлений або видалений через UI або API.

Користувачі тенанта можуть бути адміністраторами з усіма правами та доступом до Tenant, або їм можуть бути надані обмежені права для модерування коментарів, доступу до ключів API тощо.

Структура об'єкта TenantUser наведена нижче:

Структура 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.

Вартість базується на кількості повернутих користувачів тенанта, становить 1 credit per 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 має бути в списку Підтримувані локалі.
username має бути унікальним у межах всього FastComments.com. Якщо це проблема, ми радимо використовувати SSO.
email має бути унікальним у межах всього FastComments.com. Якщо це проблема, ми радимо використовувати SSO.
Ви не можете створити більше TenantUser, ніж визначено в 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:

The TenantUser must already exist.
You must have access to manage the Tenant the TenantUser belongs to.

Ми можемо надіслати посилання для входу 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

This route provides the ability to update a single TenantUser.

Updating a TenantUser has the following restrictions:

The signUpDate may not be in the future.
The locale must be in the list of Підтримувані локалі.
The username must be unique across all of FastComments.com. If this is an issue, we suggest using SSO instead.
The email must be unique across all of FastComments.com. If this is an issue, we suggest using SSO instead.
You cannot update the tenantId of a user.

We can create a TenantUser as follows

Приклад 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 (тепер сирітські) коментарі будуть видалені або анонімізовані залежно від конфігурації сторінки, пов'язаної з кожним коментарем. Наприклад, якщо режим видалення нитки — "анонімізувати", тоді відповіді залишаться, а коментарі користувача будуть анонімізовані. Це застосовується лише коли 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 у нас є кілька різних сценаріїв використання для користувачів:

Безпечний SSO
Простий SSO
Користувачі орендаря (наприклад: Адміністратори)
Коментатори

Цей API призначений для Коментаторів та користувачів, створених через Простий SSO. Насправді будь-який користувач, створений через ваш сайт, може бути отриманий через цей API. Користувачів орендаря також можна отримати цим способом, але ви отримаєте більше інформації, взаємодіючи з /tenant-users/ API.

Для Secure SSO будь ласка використовуйте /sso-users/ API.

Ви не можете оновлювати ці типи користувачів. Вони створили свій акаунт через ваш сайт, тому ми надаємо базовий доступ лише для читання, але ви не можете вносити зміни. Якщо ви хочете мати такий тип потоку — вам потрібно налаштувати 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-запиту User за id

Copy

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

Структура запиту User

Copy

interface UserByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Структура відповіді User

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 key.

Структура appliedAnonymousVotes призначена для голосів, створених без електронної пошти, API key тощо.

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
}

Creating Anonymous Votes

Анонімні голоси можна створити, встановивши anonUserId в параметрах запиту замість userId.

This id does not have to correspond to a user object anywhere (hence anonymous). It is simply an identifier for the session, so you can fetch votes again in the same session, to check if a comment has been voted.

If you do not have such a thing as "anonymous sessions" like FastComments does - you can simply set this to a random ID, like a UUID (although we appreciate smaller identifiers to save space).

Other Notes

This API obeys tenant-level settings. For example, if you disable voting for a given page, and you attempt to create a vote via the API, it will fail with error code voting-disabled.
This API is live by default.
This API will update the votes of the corresponding 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.

Структура конфігурації домену

Об'єкт DomainConfig представляє конфігурацію для домену для орендаря.

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

Структура конфігурації домену

Copy

interface DomainConfig {
    /** Домен, а не URL, наприклад "fastcomments.com" або "www.example.com". Можна вказати піддомен, якщо потрібно обмежити до піддомену. Максимум 1000 символів. **/
    domain: string
    /** Ім'я відправника, яке використовується при надсиланні електронних листів. **/
    emailFromName?: string
    /** Адреса електронної пошти відправника (From-Email), яка використовується при надсиланні листів. Переконайтеся, що SPF налаштовано, щоб дозволити mail.fastcomments.com відправляти листи від імені домену, вказаного в цьому атрибуті. **/
    emailFromEmail?: string
    /** READONLY. When the object was created. **/
    createdAt: string
    /** Логотип, пов'язаний із цим доменом. Використовується в листах. Використовуйте HTTPS. **/
    logoSrc?: string
    /** Менший логотип, пов'язаний із цим доменом. Використовуйте HTTPS. **/
    logoSrc100px?: string
    /** SSO ONLY. The URL used in the footer of every email sent. Supports a "[userId]" variable. **/
    footerUnsubscribeURL?: string
    /** SSO ONLY. The headers used in of every email sent. Useful for example for setting unsubscribe related headers to improve delivery. The List-Unsubscribe entry in this Record, if it exists, supports a "[userId]" variable. **/
    emailHeaders?: Record<string, string>
    /** Disable all unsubscribe links. Not recommended, may hurt delivery rates. **/
    disableUnsubscribeLinks?: boolean
    /** DKIM Configuration. **/
    dkim?: DomainConfigDKIM
}

Структура конфігурації DKIM

Copy

interface DomainConfigDKIM {
    /** The domain name in your DKIM record. **/
    domainName: string
    /** The DKIM key selector to use. **/
    keySelector: string
    /** The public key, in PEM format. Returned in GET responses. **/
    publicKey: string
    /** @deprecated No longer returned in API responses. Accepted on write for backwards compatibility. **/
    privateKey?: string
}

Для автентифікації

Domain Configuration is used to determine which sites can host the FastComments widget for your account. This is a basic form of authentication, meaning adding or removing any Domain Configurations can impact the availability of your FastComments installation in production.

Don't remove or update the domain property of a Domain Config for a domain that is currently in use unless disabling that domain is intended.

This has the same behavior as removing a domain from /auth/my-account/configure-domains.

Also note that removing a domain from the My Domains UI will remove any corresponding configuration for that domain that may have been added via this UI.

Для налаштування електронної пошти

The unsubscribe link in the email footer, and the one-click-unsubscribe feature offered by many email clients, can be configured via this API by defining footerUnsubscribeURL and emailHeaders, respectively.

Для DKIM

After defining your DKIM DNS records, simply update the DomainConfig with your DKIM configuration using the defined structure.

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 запиту PATCH для DomainConfig

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",
}'

Структура PATCH-запиту DomainConfig

Copy

interface DomainConfigPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Структура PATCH-відповіді DomainConfig

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 за id.

Примітка: Видалення DomainConfig анулює авторизацію цього домену для використання FastComments.
Примітка: Повторне додавання домену через інтерфейс користувача відтворить об'єкт (зі значенням лише в полі 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).

Приклад 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'
    /** Included on failure. **/
    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
}'

Структура POST-запиту QuestionConfig

Copy

interface QuestionConfigPostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура відповіді POST для QuestionConfig

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 POST для QuestionResult

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'
    /** Агрегувати для певної сторінки. **/
    urlId?: string
    /** Агрегувати для конкретного користувача. **/
    userId?: string
    /** Примусово перерахувати зараз і оновити кеш. **/
    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'
    /** Включається у разі помилки. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Включається у разі помилки. **/
    reason?: string
    data: QuestionResultsAggregationResult
}

Примітки щодо продуктивності

У разі промаху кеша (cache miss) агрегація зазвичай займає п'ять секунд на мільйон результатів.
В іншому випадку запити виконуються за константний час.

Примітки щодо кешування та вартості

Коли зазначено 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.

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

Структура об'єкта 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
    /** Колір фону бейджа (шістнадцятковий код) */
    backgroundColor?: string
    /** Колір рамки бейджа (шістнадцятковий код) */
    borderColor?: string
    /** Колір тексту на бейджі (шістнадцятковий код) */
    textColor?: string
    /** Додатковий CSS-клас для стилізації */
    cssClass?: string
    /** Для бейджів ветерана — часовий поріг у мілісекундах */
    veteranUserThresholdMillis?: number
    /** Чи відображається цей бейдж у коментарях користувача */
    displayedOnComments: boolean
    /** Порядок відображення бейджа */
    order?: number
    /** Якщо встановлено, цей бейдж відображається лише на сторінці з відповідним urlId. Null для глобальних бейджів. */
    urlId?: string | null
}

GET /api/v1/user-badges

Цей кінцевий пункт API дозволяє отримувати значки користувачів за різними критеріями.

Приклад запиту:

Список значків користувача - приклад 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

Ця кінцева точка дозволяє отримати конкретний значок користувача за його унікальним ідентифікатором.

Приклад запиту:

Приклад 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
  }
}

Можливі відповіді з помилками:

Помилка: відсутній 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 badge123 was not found."
}

---

POST /api/v1/user-badges

Цей 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 (required) - Ідентифікатор користувача, якому призначається бейдж
badgeId (required) - Ідентифікатор бейджа, який призначається
displayedOnComments (optional) - Чи має бейдж відображатися у коментарях користувача (за замовчуванням true)

Important Notes:

The badge must exist and be enabled in your tenant's badge catalog
You can only assign badges to users who belong to your tenant or have commented on your site

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:

Помилка: відсутній 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": "User ID (body param: userId) is required."
}

Помилка: відсутній Badge ID

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

Ця кінцева точка дозволяє оновити призначення бейджу користувача.

Наразі єдина властивість, яку можна оновити, — 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

Цей endpoint дозволяє видалити призначення бейджа користувача.

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 орендаря (tenant), якому належить цей запис прогресу */
    tenantId: string
    /** ID користувача, за яким відстежується цей запис прогресу */
    userId: string
    /** ID першого коментаря користувача в системі */
    firstCommentId?: string
    /** Дата першого коментаря користувача (мілісекунди від початку епохи) */
    firstCommentDate?: number
    /** Автоматично обчислений коефіцієнт довіри на основі активності користувача */
    autoTrustFactor?: number
    /** Коефіцієнт довіри, встановлений вручну адміністраторами */
    manualTrustFactor?: number
    /** Детальний об'єкт прогресу з різними метриками, ключі відповідають enum BadgeType */
    progress: {
        /** 0: CommentCount - Кількість коментарів, які залишив користувач */
        '0'?: number
        /** 1: CommentUpVotes - Кількість upvotes, які отримав користувач */
        '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
      }
    }
  ]
}

Можливі відповіді з помилкою:

Помилка: Відсутній 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-badge-progress/: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

Цей endpoint дозволяє отримати запис про прогрес бейджів користувача за його 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 користувачі

Підписки

Щоденне використання орендаря

Орендарі

Пакети орендаря

Користувачі орендаря

Користувачі

Голоси

Конфігурації домену

Конфігурації питань

Результати питань

Агрегація результатів питань

Значки користувачів

Прогрес значка користувача

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

API FastComments

Згенеровані SDK

Аутентифікація

Примітка щодо безпеки

Варіант аутентифікації 1 — Заголовки

Варіант аутентифікації 2 — Параметри запиту

Варіант аутентифікації 3 — OAuth Bearer Token

Читання власних записів

Ресурси API

Використання ресурсів

Примітка!

Вебхуки

Авторизація OAuth

Discovery

Реєстрація клієнта

Скоупи

Крок 1 – Запит авторизації

Крок 2 – Запит токену

Крок 3 – Виклик API

Крок 4 – Оновлення

Відкликання

Агрегуйте ваші дані

Приклади

Приклад: Підрахунок унікальних

Приклад: Підрахунок різних

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

Приклад: Середні значення кількох полів

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

Приклад: Підрахунок унікальних значень кількох полів

Приклад: Створення запиту

Приклад: Підрахунок коментарів, що очікують перевірки

Приклад: Розподіл схвалених, перевірених та спам-коментарів

Структури

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

GET /api/v1/audit-logs

Пошук того, що сталося з особою

Керовані орендарі

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

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

Тегування

Хештеги

GET /api/v1/comments

Пагінація

Теми

Пояснення дерев

Отримання коментарів у контексті користувача

Отримати коментарі у вигляді дерева