API | FastComments Docs

API платформе FastComments

FastComments обезбеђује API за интеракцију са многим ресурсима. Изградите интеграције са нашом платформом, или чак направите своје клијенте!

У овој документацији наћи ћете све ресурсе које API подржава, са документацијом њихових типова захтева и одговора.

За Enterprise кориснике, сав приступ API-ју се бележи у Audit Log.

Generated SDKs

FastComments сада генерише API Spec из нашег кода (ово још није потпуно, али укључује многе API-је).

Такође сада имамо SDK-ове за популарне језике:

Аутентификација

API се аутентификује прослеђивањем вашег api key као или X-API-KEY заглавља или као API_KEY query параметра. Такође ће вам требати ваш tenantId за позиве API-ја. Он се може преузети са исте странице као и ваш api key.

Напомена о безбедности

Ове руте треба позивати са сервера. НЕ ПОЗИВАЈТЕ их из прегледача. То би открило ваш API key - то ће омогућити пун приступ вашем налогу било коме ко може видети изворни код странице!

Authentication Option One - Headers

Заглавље: X-API-KEY
Заглавље: X-TENANT-ID

Authentication Option Two - Query Parameters

Параметар упита: API_KEY
Параметар упита: tenantId

API ресурси

Korišćenje resursa

Treba napomenuti da se preuzimanje podataka sa API-ja računa kao potrošnja na vašem nalogu.

Svaki resurs će u svojoj sekciji navesti kolika je ta potrošnja.

Neki resursi su skuplji za posluživanje od drugih. Svaki endpoint ima fiksnu cenu u kreditima po API pozivu. Za neke endpoint-e, broj kredita varira u zavisnosti od opcija i veličine odgovora.

Upotreba API-ja se može proveriti na stranici Analitika naplate i ažurira se svakih nekoliko minuta.

Napomena!

Preporučujemo da prvo pročitate dokumentaciju Pages, kako biste smanjili zabunu prilikom određivanja koje vrednosti treba proslediti za urlId u Comment API-ju.

Агрегирајте своје податке

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

Ovaj API agregira dokumente grupišući ih (ako je naveden groupBy) i primenjujući više operacija. Podržane su različite operacije (npr. sum, countDistinct, avg, itd.).

Cena je varijabilna. Na svakih 500 pregledanih objekata troši se 1 API kredit.

Maksimalna dozvoljena upotreba memorije po API pozivu podrazumevano je 64MB, i podrazumevano možete imati samo jednu agregaciju koja radi u jednom trenutku. Ako pošaljete više agregacija istovremeno, biće stavljene u red i izvršene redosledom slanja. Agregacije koje čekaju biće zadržane najduže 60 sekundi, nakon čega će zahtev isteći (timeout). Pojedinačne agregacije mogu se izvršavati do 5 minuta.

Ako imate upravljane tenante, možete agregirati sve resurse podređenih tenant-a u jednom pozivu tako što ćete proslediti query parametar parentTenantId.

Primeri

Primer: Brojanje jedinstvenih

Primer cURL zahteva: Brojanje jedinstvenih vrednosti

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

Odgovor: Brojanje jedinstvenih vrednosti

Copy

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

Primer: Prebrojavanje različitih vrednosti

Primer cURL zahteva: Prebrojavanje različitih vrednosti

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

Odgovor:

Odgovor: Prebrojavanje različitih vrednosti

Copy

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

Primer: Sabiranje vrednosti više polja

Primer cURL zahteva: Sabiranje vrednosti

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

Odgovor:

Odgovor: Sabiranje vrednosti

Copy

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

Primer: Prosečne vrednosti više polja

Primer cURL zahteva: Prosečne vrednosti

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

Odgovor:

Odgovor: Prosečne vrednosti

Copy

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

Primer: Minimalne/Maksimalne vrednosti više polja

Primer cURL zahteva: Minimalne/Maksimalne vrednosti

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

Odgovor:

Odgovor: Minimalne/Maksimalne vrednosti

Copy

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

Primer: Brojanje jedinstvenih vrednosti više polja

Primer cURL zahteva: Brojanje jedinstvenih vrednosti

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

Odgovor:

Odgovor: Brojanje jedinstvenih vrednosti

Copy

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

Primer: Kreiranje upita

Primer cURL zahteva: Kreiranje upita

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

Odgovor:

Odgovor: Kreiranje upita

Copy

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

Primer: Brojanje komentara na čekanju za pregled

Primer cURL zahteva: Brojanje komentara na čekanju za pregled

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

Odgovor:

Odgovor: Brojanje komentara na čekanju za pregled

Copy

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

Primer: Raspodela odobrenih, pregledanih i spam komentara

Primer cURL zahteva: Raspodela komentara

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

Odgovor:

Odgovor: Raspodela komentara

Copy

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

Strukture

Struktura zahteva za agregaciju

Copy

export type AggregationOpType = 'sum' | 'countDistinct' | 'distinct' | 'avg' | 'min' | 'max' | 'count';
/** Operacija koja će se primeniti na polje */
export interface AggregationOperation {
    /** Polje na kojem će se operacija izvršiti */
    field: string;
    /** Tip operacije */
    op: AggregationOpType;
    /** Opcioni alias za izlaz; ako nije naveden, izračunava se podrazumevani alias */
    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
};

Struktura odgovora za agregaciju

Copy

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

Sledeći resursi mogu biti agregirani:

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

Структура дневника ревизије

А AuditLog је објекат који представља ревидирани догађај за тенанте који имају приступ овој функцији.

Структура објекта AuditLog је следећа:

Структура AuditLog

Copy

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

Аудит лог је неменљив. Такође му се не може ручно писати. FastComments.com може једино одлучити када ће уписати у аудит лог. Међутим, ви можете читати из њега преко овог API-ја.

Догађаји у аудит логу истичу након две године.

GET /api/v1/audit-logs

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

Овај API користи пагинацију, обезбеђену параметрима skip, before и after. AuditLogs се враћају у страницама по 1000, сортиране по when и id.

Повлачење сваке 1000 ставке кошта 10 кредита.

Подразумевано ћете добити листу са најновијим ставкама прво. На тај начин можете почети са skip=0, пагинирајући док не пронађете последњи запис који сте обрадили.

Алтернативно, можете сортирати од најстаријих прво и пагинирати док не буде више записа.

Сортирање се врши постављањем параметра order на ASC или DESC. Подразумевана вредност је ASC.

Претраживање по датуму је могуће помоћу before и after као временских ознака у милисекундама. before и after нису укључиви.

Пример cURL захтева за AuditLog

Copy

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

Структура захтева за AuditLog

Copy

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

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

Copy

interface CommentsResponse {
    status: 'success' | 'failed'
    /** Укључено у случају неуспеха. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Укључено у случају неуспеха. **/
    reason?: string
    /** Записи дневника! **/
    auditLogs: AuditLog[]
}

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

A Comment object представља коментар који је оставио корисник.

Однос између родитељских и дечијих коментара је дефинисан преко parentId.

Структура Comment објекта је следећа:

Struktura komentara

Copy

interface Comment {
    /** READONLY: Поставити на true ако је spam механизам утврдио да је коментар спам. **/
    aiDeterminedSpam?: boolean
    /** Да ли је коментар одобрен за приказ. Поставити на true приликом чувања коментара, иначе ће бити скривен. **/
    approved?: boolean
    /** Корисников аватар. **/
    avatarSrc?: string
    /** Дечији коментари. Нису попуњени у свим сценаријима. Користе се када је asTree постављен на true преко API-ја. **/
    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
    /** Број #hahtag-ова написаних у коментару који су успешно парсирани. Такође можете ручно додавати хештегове за упите, али они се неће аутоматски приказати у тексту коментара. **/
    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 ако је коментар soft obrisan (морао је бити остављен плејсхолдер због неког другог подешавања). **/
    isDeleted?: boolean
    /** Поставити на true ако је кориснички налог обрисан, а коментар је морао бити сачуван. **/
    isDeletedUser?: boolean
    /** READONLY: Да ли је коментар означен од стране тренутно пријављеног корисника (contextUserId)? **/
    isFlagged?: boolean
    /** Да ли је коментар причвршћен (pinned)? **/
    isPinned?: boolean
    /** Да ли је коментар закључан за нове одговоре (модератори и даље могу одговорити)? **/
    isLocked?: boolean
    /** Да ли је коментар спам? **/
    isSpam?: boolean
    /** READONLY: Да ли је коментар негативно гласан за тренутног корисника (contextUserId)? **/
    isVotedDown?: boolean
    /** READONLY: Да ли је коментар позитивно гласан за тренутног корисника (contextUserId)? **/
    isVotedUp?: boolean
    /** Локал у којем је коментар. Ако није обезбеђен, изведе се из HTTP header-a за језик (accept). **/
    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 написани у коментару који су успешно парсирани. **/
    mentions?: CommentUserMention[]
    /** Опционални метаподатак повезан са коментаром. **/
    meta?: Record<string, string | number | boolean>
    /** Опциона листа id-јева модерацијских група повезаних са овим коментаром. **/
    moderationGroupIds?: string[]|null
    /** READONLY: Ид гласа који одговара гласу од тренутног корисника (contextUserId) за овај коментар. **/
    myVoteId?: string
    /** Да ли су послате нотификације за овај коментар коментаторима. Да бисте спречили слање нотификација приликом увоза, поставите ово на true. **/
    notificationSentForParent?: boolean
    /** Да ли су послате нотификације за овај коментар tenant корисницима. Да бисте спречили слање нотификација приликом увоза, поставите ово на true. **/
    notificationSentForParentTenant?: boolean
    /** Наслов странице на којој се овај коментар налазио. **/
    pageTitle?: string
    /** Ако одговарамо на коментар, ово је ID на који одговарамо. **/
    parentId?: string|null
    /** Да ли је коментар означен као прегледан (reviewed). **/
    reviewed: boolean
    /** Tenant id где коментар припада. **/
    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-ја али не могу бити подешавана.

Struktura teksta komentara

Коментари су написани у FastComments варијанти markdown-а, која је у основи 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-а, па је прављење renderer-а прилично једноставно. Постоји више библиотека за React Native и Flutter, на пример, које могу помоћи у томе.

Можете изабрати да рендерујете нормализовану или ненормализовану вредност поља comment. Пример парсера је овде..

Пример парсера се такође може прилагодити да ради са HTML-ом и трансформише HTML тагове у очекиване елементе за рендеровање на вашој платформи.

Obeležavanje

Када су корисници означени у коментару, информација се чува у листи која се зове mentions. Сваки објекат у тој листи има следећу структуру.

Objekat pomena u komentaru

Copy

Run

interface CommentUserMention {
    /** ID корисника. За SSO кориснике, ово ће имати ваш tenant id као префикс. **/
    id: string
    /** Коначни @mention tag текст, укључујући @ симбол. **/
    tag: string
    /** Оригинални @mention tag текст, укључујући @ симбол. **/
    rawTag: string
    /** Која врста корисника је означена. user = FastComments.com налог. sso = SSOUser. **/
    type: 'user'|'sso'
    /** Ако се корисник одјави од нотификација, ово ће и даље бити постављено на true. **/
    sent: boolean
}

Haštagovi

Када се хештегови користе и успешно парсирају, информација се чува у листи која се зове hashTags. Сваки објекат у тој листи има следећу структуру. Хештегови се такође могу ручно додати у низ hashTags коментара за упите, ако је retain постављен.

Objekat haštaga u komentaru

Copy

Run

interface CommentHashTag {
    /** ID хештега. **/
    id: string
    /** Коначни #hashtag tag текст, укључујући # симбол. **/
    tag: string
    /** Ако је хештег повезан са прилагођеним URL-ом, ово ће бити дефинисано. **/
    url?: string
    /** Ако треба да задржимо хештег, чак и ако он не постоји у тексту коментара када се коментар ажурира. Корисно за означавање коментара без мењања текста коментара. **/
    retain?: boolean
}

GET /api/v1/comments

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

Овај API се користи за добијање коментара који ће бити приказани кориснику. На пример, аутоматски филтрира неприхваћене или спам коментаре.

Пагинација

Пагинација се може извести на један од два начина, у зависности од захтева за перформансама и случаја употребе:

Најбрже: Прерачуната пагинација:
1. Ово је начин на који FastComments ради када користите наше унапред направљене видгете и клијенте.
2. Клик на "next" једноставно увећава број странице.
3. Можете ово сматрати као да је дохваћено из key-value продавнице.
4. На овај начин, једноставно дефинишете параметар page који почиње од 0 и смер сортирања као direction.
5. Величине страница се могу прилагодити преко правила прилагођавања.
Најфлексибилније: Флексибилна пагинација:
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 деце.
3. Пример слике који илуструје више страна.
Када користите Flexible Pagination, можете дефинисати параметар parentId.
1. Поставите га на null да бисте добили само коментаре највишег нивоа.
2. Затим, да бисте видели тредове, позовите API поново и проследите parentId.
3. Уобичајено решење је да направите позив 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 се може користити у два контекста, за различите случајеве употребе:

За враћање коментара сортираних и означених информацијама за израду сопственог клијента.
- У овом случају дефинишите query параметар 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'

Међутим, у вашем UI-у можда ћете морати да знате да ли да прикажете дугме „пкажи одговоре“ на сваком коментару. Када се коментари дохватају као стабло, постоји својство hasChildren које је додато коментарима када је применљиво.

Добијање коментара као стабло, претраживање по хештегу

Могуће је претраживати по хештегу користећи API, преко целог вашег tenant-а (није ограничено на једну страницу или 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
    /** The urlId (page url, or article id) the comments are associated with. **/
    urlId?: string
    /** Limit the comments returned by this user. **/
    userId?: string
    /** Use this to search by hashtag. To drill down to the intersection of multiple hashtags, do &hashTag=a&hashTag=b. **/
    hashTag?: string
    /** The sort direction. Default is MR (Most Relevant). Other options are OF (Oldest First) and NF (Newest First). **/
    direction?: 'MR' | 'OF' | 'NF'
    /** Precalculated Pagination: The page to fetch, starting with 0. Pass -1 for all comments (up to 250). **/
    page?: number
    /** Flexible Pagination: How many comments should we return? **/
    limit?: number
    /** Flexible Pagination: How many child comments should we return for each parent? **/
    limitChildren?: number
    /** Flexible Pagination: How many comments should we skip? **/
    skip?: number
    /** Flexible Pagination: How many child comments should we skip for each parent? **/
    skipChildren?: number
    /** For determining blocked and flagged comments. **/
    contextUserId?: string
    /** For determining blocked and flagged comments. **/
    anonUserId?: string
    /** For fetching child comments. **/
    parentId?: string
    /** For fetching as a tree. **/
    asTree?: boolean
    /** How far into the tree should we return data? 0 returns no children. 1 returns immediate children, etc. **/
    maxTreeDepth?: number
}

Одговор

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

Copy

interface CommentsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    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'
    /** Included on failure. **/
    reason?: string
    /** The comments! **/
    comments: Comment[]
}

Корисни савети

URL ID

Вероватно ћете желети да користите Comment API са параметром urlId. Можете позвати Pages API прво, да видите како изгледају вредности urlId које су вам доступне.

Анонимне радње

За анонимно коментарисање вероватно ћете желети да проследите anonUserId када дохватате коментаре, и када извршавате означавање (flagging) и блокирање.

(!) Ово је захтевано за многе продавнице апликација јер корисници морају моћи да означавају садржај који су креирали други корисници и који могу видети, чак и ако нису пријављени. Ако то не учините, ваша апликација може бити уклоњена из те продавнице.

Коментари се не враћају

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

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 може ажурирати видгет за коментаре "уживо" ако је потребно (ово повећава creditsCost са 1 на 2).
Овај API ће аутоматски креирати објекте корисника у нашем систему ако је е-пошта наведена.
Покушај да се сачувају два коментара са различитим е-поштама, али истим корисничким именом, довешће до грешке за други коментар.
Ако наведете parentId, и ако дечји коментар има notificationSentForParent као false, послаћемо обавештења за родитељски коментар. Ово се ради сваки сат (групишемо обавештења како бисмо смањили број послатих е-порука).
Ако желите да пошаљете поздравне е-поруке при креирању корисника, или е-поруке за верификацију коментара, поставите sendEmails на true у параметрима упита.
Коментари креирани преко овог API-ја ће се појавити на страницама Аналитике и Модерације у админ апликацији.
„лоше речи“ се и даље замагљују у именима коментатора и тексту коментара ако је подешавање укључено.
Коментари креирани путем овог API-ја и даље се могу проверити на спам ако је то потребно.
Конфигурација као што је максимална дужина коментара, ако је подешена преко странице правила прилагођавања у админ интерфејсу, примењиваће се и овде.

Минимални подаци потребни за слање који ће се приказати у видгету за коментаре су следећи:

Минималан пример cURL POST захтева за коментар

Copy

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

Реалнији захтев може изгледати овако:

Реалнији пример cURL POST захтева за коментар

Copy

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

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

Copy

interface CommentPostQueryParams {
    tenantId: string
    API_KEY: string
    doSpamCheck?: 'true' | 'false'
    /** Да ли коментар треба да се приказује "уживо" корисницима који гледају инстанце видгета за коментаре са истим 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-ја омогућава ажурирање појединачног коментара.

Напомене:

Овај API може ажурирати коментарски видгет "у реалном времену" ако је потребно (ово повећава основни creditsCost са 1 на 2).
- Ово може омогућити миграцију коментара између страница "у реалном времену" (промена urlId).
- Миграције коштају додатна 2 кредита јер се странице предрачунавају и ово је CPU интензивно.
За разлику од API-ја за креирање, овај API НЕће аутоматски креирати корисничке објекте у нашем систему ако је наведена е-пошта.
Коментари ажурирани преко овог API-ја и даље могу бити проверавани на спам ако је то по жељи.
Конфигурације као што је максимална дужина коментара, ако су подешене преко административне странице Customization Rule, примењиваће се овде.
Да бисте омогућили корисницима да ажурирају текст коментара, можете једноставно назначити comment у телу захтева. Ми ћемо генерисати резултујући commentHTML.
- Ако дефинишете и comment и commentHTML ми нећемо аутоматски генерисати HTML.
- Ако корисник дода помињања или хештегове у свом новом тексту, то ће и даље бити обрађено као у POST API-ју.
Када ажурирате commenterEmail на коментару, најбоље је такође назначити userId. У супротном, морате осигурати да корисник са том е-поштом припада вашем тенанту, или ће захтев не успети.

Минимални пример 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'
    /** Укључено у случају неуспеха. **/
    reason?: string
}

DELETE /api/v1/comments/:id

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

Овај API ендпоинт омогућава брисање коментара.

Напомене:

Овај API може ажурирати видгет коментара "live" ако је потребно (ово увећава creditsCost са 1 на 2).
Овај API ће избрисати све подкоментаре.

cURL пример за брисање коментара

Copy

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

Структура захтева за брисање коментара

Copy

interface CommentDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** Корисник који врши ажурирање. По потреби се може користити да се провери да ли он/она може обрисати коментар.  **/
    contextUserId?: string
    /** Да ли коментар треба да буде обрисан "live" за кориснике који гледају инстанце видгета за коментаре са истим urlId. НАПОМЕНА: Удвостручује трошак кредита са 1 на 2. **/
    isLive?: 'true' | 'false'
}

Структура одговора за брисање коментара

Copy

interface CommentDeleteResponse {
    status: 'success' | 'failed'
    /** Укључено у случају неуспеха. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Укључено у случају неуспеха. **/
    reason?: string
}

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

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

Овај API ендпоинт омогућава означавање коментара за одређеног корисника.

Напомене:

Овај позив увек мора бити извршен у контексту корисника. Корисник може бити FastComments.com User, SSO User, или Tenant User.
Ако је постављен праг за сакривање након пријављивања, коментар ће бити аутоматски сакривен уживо након што буде означен онај број пута који је дефинисан.
Након што буде аутоматски поништено одобрење (скривен) — коментар може поново одобрити само администратор или модератор. Уклањање пријаве неће поново одобрити коментар.

Пример 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. Ово може бити ID који представља анонимну сесију, или случајни UUID. Ово нам омогућава подршку за пријављивање и укидање пријаве коментара чак и ако корисник није пријављен. На овај начин, коментар може бити означен као пријављен када се коментари преузму са истим 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 ендпоинт пружа могућност уклањања ознаке (un-flag) коментара за одређеног корисника.

Напомене:

Овaј захтев увек мора бити извршен у контексту корисника. Корисник може бити FastComments.com корисник, SSO корисник, или Tenant корисник.
Након што је коментар аутоматски означен као неприхваћен (скривен) - коментар може бити поново одобрен само од стране администратора или модератора. Уклањање ознаке (un-flag) неће поново одобрити коментар.

Пример 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.
Потпуно анонимни коментари (нема user id, нема email) не могу бити блокирани и враћа се грешка.

Пример cURL захтева за блокирање коментара

Copy

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

За анонимно блокирање, морамо назначити anonUserId. Ово може бити ID који представља анонимну сесију, или случајни 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 endpoint омогућава де-блокирање корисника који је написао одређени коментар. Подржава де-блокирање на основу коментара које су написали FastComments.com Users, SSO Users и Tenant Users.

Подржава параметар у телу захтева commentIdsToCheck да провери да ли неки други потенцијално видљиви коментари на клијенту треба да буду блокирани/де-блокирани након извршене радње.

Напомене:

Овај позив мора увек бити извршен у контексту корисника. Корисник може бити FastComments.com User, SSO User или Tenant User.
userId у захтеву је корисник који врши де-блокирање. На пример: User A wants to Un-Block User B. Проследите userId=User A и ID коментара који је написао User B.
Потпуно анонимни коментари (без ID-а корисника, без е-поште) не могу бити блокирани и биће враћена грешка.

Primer cURL zahteva za deblokiranje komentara

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'

Primer cURL zahteva za deblokiranje anonimnog komentara

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'

Struktura zahteva za deblokiranje komentara

Copy

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

Struktura odgovora za deblokiranje komentara

Copy

interface CommentUnBlockResponse {
    status: 'success' | 'failed'
    /** Uključeno u slučaju neuspeha. **/
    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'
    /** Uključeno u slučaju neuspeha. **/
    reason?: string
    /** Ako je commentIdsToCheck definisan, unosi u ovoj mapi са 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

Појединачни EmailTemplates могу се преузети помоћу одговарајућег id (НЕ emailTemplateId).

EmailTemplate по ID — пример cURL

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.

EmailTemplate cURL пример

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'
    /** Included on failure. **/
    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 за EmailTemplate PATCH

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

Структура захтева за EmailTemplate PATCH

Copy

interface EmailTemplatePatchQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface EmailTemplatePatchResponse {
    status: 'success' | 'failed'
    /** Укључено у случају неуспеха. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'not-found' | 'unexpected-param' | 'invalid-email-template-id' | 'unauthorized' | 'domain-invalid' | 'duplicate' | 'does-not-render';  
    /** Укључено у случају неуспеха. **/
    reason?: string
    /** Ажурирани шаблон е-поште. **/
    emailTemplate?: EmailTemplate
}

POST /api/v1/email-templates

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

Ова API крајња тачка омогућава креирање шаблона е-поште.

Напомене:

Не можете имати више шаблона са истим emailTemplateId за исти домен.
Међутим, можете имати wildcard шаблон (domain = *) и домен-специфичан шаблон за исти emailTemplateId.
Навођење domain је релевантно само ако имате више домена, или желите да користите специфичне шаблоне за тестирање (domain подешен на localhost итд).
Ако наведете domain, он мора да одговара DomainConfig. У случају грешке биће дат списак валидних домена.
Синтакса шаблона је EJS и рендерује се са timeout-ом од 500ms. P99 за рендеровање је <5ms, па ако достигнете 500ms нешто је погрешно.
Ваш шаблон мора да се рендерује са датим testData да би се сачувао. Грешке приликом рендеровања се агрегирају и пријављују на контролној табли (ускоро доступно преко API-ја).

Минимални подаци потребни за додавање шаблона су следећи:

Минималан EmailTemplate POST cURL пример

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:

EmailTemplate POST cURL пример

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

Структура 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' | 'invalid-email-template-id' | 'domain-invalid' | 'duplicate' | 'does-not-render';
    /** Укључено у случају неуспеха. **/
    reason?: string
    /** Креирани шаблон. **/
    emailTemplate?: EmailTemplate
}

POST /api/v1/email-templates/render

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

Ова API крајња тачка омогућава преглед шаблона е-поште.

Минимални cURL пример за POST преглед EmailTemplate

Copy

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

Структура POST захтева за EmailTemplate

Copy

interface EmailTemplatePostQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface EmailTemplatePostResponse {
    status: 'success' | 'failed'
    /** Укључено у случају неуспеха. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'unexpected-param' | 'does-not-render';
    /** Укључено у случају неуспеха. **/
    reason?: string
    /** Рендеровани HTML у случају успеха. **/
    html?: string
}

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

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

Ова рута омогућава уклањање појединачног EmailTemplate по id-у.

Пример cURL захтева за уклањање EmailTemplate-а

Copy

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

Структура захтева за уклањање EmailTemplate-а

Copy

interface EmailTemplateRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Структура одговора за уклањање EmailTemplate-а

Copy

interface EmailTemplateDeleteResponse {
    status: 'success' | 'failed'
    /** Укључено у случају неуспеха. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized'
    /** Укључено у случају неуспеха. **/
    reason?: string
}

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

Објекат HashTag представља ознаку коју може оставити корисник. HashTags се могу користити за повезивање на спољни садржај или за повезивање релевантних коментара.

Структура за објекат HashTag је следећа:

Структура HashTag-а

Copy

interface HashTag {
    /** Треба да почиње са "#" или жељеним знаком. **/
    tag: string
    /** Опционо URL на који хештег може да упућује. Уместо филтрирања коментара по хештегу, UI ће при клику преусмерити на овај URL. **/
    url?: string
    /** САМО ЗА ЧИТАЊЕ **/
    createdAt: string
}

Напомене:

На неким API endpoint-има ћете видети да се хештег користи у URL-у. Запамтите да вредности треба URI-кодирати. На пример, # би требало да буде представљено као %23.
Нека од ових поља су означена као READONLY - она су враћена од стране API-ја али их није могуће подесити.

GET /api/v1/hash-tags

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

Овај API користи пагинацију, коју обезбеђује параметар упита page. HashTags се враћају страницама по 100, сортирани по tag.

HashTag cURL пример

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

Ova ruta omogućava ažuriranje jedne HashTag.

Primer cURL zahteva za ažuriranje HashTag-a

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

Struktura zahteva za ažuriranje HashTag-a

Copy

interface HashTagPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Struktura odgovora za ažuriranje HashTag-a

Copy

interface HashTagPatchResponse {
    status: 'success' | 'failed'
    /** Uključeno u slučaju neuspeha. **/
    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'
    /** Uključeno u slučaju neuspeha. **/
    reason?: string
    hashTag?: HashTag; // Vraćamo kompletan ažurirani HashTag pri uspehu.
}

POST /api/v1/hash-tags

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

Ova ruta omogućava dodavanje jednog HashTag.

Primer cURL zahteva za kreiranje HashTag-a

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

Struktura zahteva za kreiranje HashTag-a

Copy

interface HashTagPostQueryParams {
    tenantId: string
    API_KEY: string
}

Struktura odgovora za kreiranje HashTag-a

Copy

interface HashTagPostResponse {
    status: 'success' | 'failed'
    /** Uključeno u slučaju neuspeha. **/
    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'
    /** Uključeno u slučaju neuspeha. **/
    reason?: string
    hashTag?: HashTag; // Vraćamo kompletan kreirani hashtag u slučaju uspeha.
}

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
}

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

Objekat Moderator predstavlja konfiguraciju za moderatora.

Постоје три типа модератора:

Администраторски корисници који имају ознаку isCommentModeratorAdmin.
SSO корисници са ознаком isCommentModeratorAdmin.
Редовни коментатори, или FastComments.com корисници, који су позвани као модератори.

Структура Moderator се користи да представи стање модерације за случај употребе 3.

Ако желите да позовете корисника да буде модератор преко API-ја, користите Moderator API тако што ћете креирати Moderator и inviting њих.

Ако корисник нема FastComments.com налог, мејл са позивом ће им помоћи да се подесе. Ако већ има налог, они ће добити приступ модерацији вашег tenant-а и поље userId објекта Moderator ће бити ажурирано да показује на њихов налог. Ви нећете имати API приступ њиховом налогу, јер у овом случају он припада њима и управља га FastComments.com.

Ако вам је потребно потпуно управљање корисничким налогом, препоручујемо или коришћење SSO-а, или додавање њих као Корисник тенанта и затим додавање објекта Moderator ради праћења њихових статистика.

Структура Moderator се може користити као механизам за праћење статистике за случајеве употребе 1 и 2. Након креирања корисника, додајте Moderator објекат са дефинисаним userId и њихове статистике ће бити праћене на Страница модератора коментара.

Структура за објекат Moderator је следећа:

Структура Moderator

Copy

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

GET /api/v1/moderators/:id

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

Ова рута враћа једног модератора по id-у.

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

Copy

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

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

Copy

interface ModeratorByIdQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface ModeratorByIdResponse {
    status: 'success' | 'failed'
    /** Укључено у случају неуспеха. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Укључено у случају неуспеха. **/
    reason?: string
    moderator?: Moderator
}

GET /api/v1/moderators

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

Ovaj API koristi paginaciju, koja je obezbeđena skip query parametrom. Moderatori se vraćaju u stranicama po 100, sortirani po createdAt i id.

Cena se zasniva na broju vraćenih moderatora, i iznosi 1 credit per 10 vraćenih moderatora.

Primer cURL zahteva za moderatora

Copy

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

Struktura zahteva za moderatora

Copy

interface ModeratorsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** Broj moderatora koje treba preskočiti za paginaciju. **/
    skip?: number
}

Struktura odgovora za moderatora

Copy

interface ModeratorsResponse {
    status: 'success' | 'failed'
    /** Uključen u slučaju neuspeha. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Uključen u slučaju neuspeha. **/
    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

Ovaj endpoint omogućava dodavanje jednog Moderator.

Kreiranje Moderator objekta ima sledeća ograničenja:

Uvek je potrebno navesti name i email. userId je opciono.
Sledeće vrednosti ne smeju biti prosleđene prilikom kreiranja Moderator:
- acceptedInvite
- markReviewedCount
- deletedCount
- markedSpamCount
- approvedCount
- editedCount
- bannedCount
- verificationId
- createdAt
Kada je userId naveden, taj korisnik mora postojati.
Kada je userId naveden, mora pripadati istom tenantId koji je naveden u parametrima upita.
Dva moderatora u istom tenantu ne mogu biti dodata sa istim email.

Možemo kreirati Moderator za korisnika za kojeg znamo samo email:

Primer cURL zahteva za kreiranje Moderatora putem e-pošte

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

Ili možemo kreirati Moderator za korisnika koji pripada našem tenantu, kako bismo pratili njihove statistike moderacije:

Primer cURL zahteva za kreiranje Moderatora za korisnika koji pripada tenantu

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

Struktura zahteva za kreiranje Moderatora

Copy

interface ModeratorPostQueryParams {
    tenantId: string
    API_KEY: string
}

Struktura odgovora za kreiranje Moderatora

Copy

interface ModeratorPostResponse {
    status: 'success' | 'failed'
    /** Uključeno u slučaju greške. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'name-required' | 'email-required' | 'unexpected-param' | 'not-found'
    /** Uključeno u slučaju greške. **/
    reason?: string
    moderator?: Moderator; // U slučaju uspeha vraćamo kompletno kreiranog moderatora.
}

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-ja. Такође истичу након једне године.

Можете обрисати број непрочитаних обавештења корисника брисањем њиховог NotificationCount.

Структура објекта NotificationCount је следећа:

Структура NotificationCount

Copy

interface NotificationCount {
    id: string // ID корисника
    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

Ova ruta vraća jedan NotificationCount po user id. Kod SSO, user id je u formatu <tenant id>:<user id>.

Ako nema nepročitanih obaveštenja, neće postojati NotificationCount - dobićete 404.

Ovo se razlikuje od notifications/count po tome što je mnogo brže, ali ne dozvoljava filtriranje.

Primer cURL zahteva za NotificationCount po ID-ju

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

Struktura zahteva za NotificationCount

Copy

interface NotificationCountGetQueryParams {
    tenantId: string
    API_KEY: string
}

Struktura odgovora za NotificationCount

Copy

interface NotificationCountGetResponse {
    status: 'success' | 'failed'
    /** Uključeno u slučaju greške. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'not-found'
    /** Uključeno u slučaju greške. **/
    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 по id корисника. Са SSO, id корисника је у формату <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 feed и повезане интеграције.

Структура објекта 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 је само за кориснике тенанта. **/
    TrialLimits = 6,
    /** Ако сте били @поменути. **/
    Mentioned = 7
}
interface Notification {
    id: string
    tenantId: string
    /** Код SSO, user id има формат `<tenant id>:<user id>`. **/
    userId?: string
    /** Када радите са SSO, треба да бринете само о `userId`. **/
    anonUserId?: string
    /** `urlId` је готово увек дефинисан. Опционо је само за обавештења на нивоу тенанта, што је ретко. **/
    urlId?: string
    /** URL се кешира ради брзог навигације до извора обавештења. **/
    url?: string
    /** Наслов странице се кешира ради брзог прегледа извора обавештења. **/
    pageTitle?: string
    relatedObjectType: NotificationObjectType
    /** На пример, id коментара. **/
    relatedObjectId: string
    viewed: boolean
    createdAt: string // датумски низ
    type: NotificationType
    fromCommentId?: string
    fromVoteId?: string
    /** fromUserName и fromUserAvatarSrc су овде кеширани ради брзог приказивања обавештења. Ажурирају се када се корисник ажурира. **/
    fromUserName: string
    fromUserId: string
    fromUserAvatarSrc?: string
    /** Поставите ово на true да бисте престали да примате обавештења за овај објекат. **/
    optedOut?: boolean
}

GET /api/v1/notifications

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

Ova ruta vraća do 30 Notification objekata sortirano po createdAt, najnoviji prvi.

Možete filtrirati po userId. Sa SSO, korisnički id je u formatu <tenant id>:<user id>.

Primer cURL za nepročitane notifikacije korisnika

Copy

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

Struktura zahteva za notifikacije

Copy

interface NotificationsGetQueryParams {
    tenantId: string
    API_KEY: string
    /** Paginacija preskakanjem zapisa. **/
    skip?: number
    /** Filtriraj po korisniku. **/
    userId?: string
    /** Filtriraj po urlId. **/
    urlId?: string
    /** Filtriraj po izvornom komentaru. **/
    fromCommentId?: string
    /** Filtriraj po pročitanom/nepročitanom. **/
    viewed?: 'true' | 'false'
    /** Filtriraj po tipu. **/
    type?: NotificationType
}

Struktura odgovora za notifikacije

Copy

interface NotificationsGetResponse {
    status: 'success' | 'failed'
    /** Uključeno u slučaju greške. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Uključeno u slučaju greške. **/
    reason?: string
    notifications?: Notification[]
}

GET /api/v1/notifications/count

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

Ова рута враћа објекат који садржи број обавештења у параметру count.

Он је спорији од /notification-count/ и дупло скупљи по кредитима, али омогућава филтрирање по више димензија.

Можете филтрирати истим параметрима као и endpoint /notifications, као што је userId. Са SSO, кориснички id је у формату <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

Ovaj API endpoint pruža mogućnost ažuriranja Notification po id.

Ažuriranje Notification ima sledeća ograničenja:

Možete ažurirati samo sledeća polja:
- viewed
- optedOut

Primer cURL zahteva za Notification PATCH

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

Struktura zahteva za Notification PATCH

Copy

interface NotificationPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Struktura odgovora za Notification PATCH

Copy

interface NotificationPatchResponse {
    status: 'success' | 'failed'
    /** Uključeno u slučaju neuspeha. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'unauthorized' | 'not-found';  
    /** Uključeno u slučaju neuspeha. **/
    reason?: string
}

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

Објекат Page представља страницу којој може припадати много коментара. Овај однос је дефинисан по urlId.

Објекат Page чува информације као што су наслов странице, број коментара и urlId.

Структура објекта Page је следећа:

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

Copy

interface Page {
    id: string
    urlId: string
    url: string
    title?: string
    createdAt: string
    commentCount: number
    rootCommentCount: number
    /** Ако је ово подешено на null, сви SSO корисници могу видети страницу. Празна листа значи да је затворена за све кориснике. **/
    accessibleByGroupIds?: string[] | null
    /** Да ли је ова страница затворена за нове коментаре? **/
    isClosed?: boolean
}

GET /api/v1/pages

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

Тренутно можете да преузмете само све странице (или једну страницу путем /by-url-id) повезане са вашим налогом. Ако желите прецизније претраживање, контактирајте нас.

Пример cURL за странице

Copy

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

Структура захтева за странице

Copy

interface PagesRequestQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface PagesResponse {
    status: 'success' | 'failed'
    /** Укључено у случају неуспеха. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Укључено у случају неуспеха. **/
    reason?: string
    pages: Page[]
}

Корисан савет

API Comment захтева urlId. Можете прво позвати Pages API да бисте видели како изгледају вредности urlId које су вам доступне.

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

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

Појединачне странице могу бити преузете по њиховом одговарајућем urlId-у. Ово може бити корисно за преглед наслова страница или броја коментара.

cURL пример за страницу по URL ИД

Copy

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

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

Copy

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

Структура одговора за страницу по URL ID

Copy

interface PagesResponse {
    status: 'success' | 'failed'
    /** Укључено у случају неуспеха. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id'
    /** Укључено у случају неуспеха. **/
    reason?: string
    page?: Page[] | null
}

Корисан савет

Запамтите да вредности као што је 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 се аутоматски ажурирају. То су бројеви и атрибути title. Бројеви не могу бити ажурирани преко API-ја јер су то израчунате вредности. Параметар странице title може бити подешен преко API-ја, али ће бити преписан ако се видгет за коментаре користи на страници са истим urlId и другачијим насловом странице.

POST /api/v1/pages

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

Овај API ендпоинт омогућава креирање страница.

Чест случај употребе је контрола приступа.

Напомене:

Ако сте коментарисали у нити коментара, или позвали API да бисте креирали Comment, ви сте већ креирали Page објекат! Можете покушати да га преузмете преко /by-url-id Page руте, прослеђујући исти urlId који сте проследили у видгету за коментаре.
Структура Page садржи неке израчунате вредности. Тренутно то су commentCount и rootCommentCount. Оне се попуњавају аутоматски и не могу се поставити преко API-ја. Покушај да се то уради ће узроковати да API врати грешку.

Пример cURL захтева за Page POST

Copy

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

Структура Page POST захтева

Copy

interface PagePostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура одговора Page POST

Copy

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

DELETE /api/v1/pages/:id

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

Ова рута омогућава уклањање једне странице по id-у.

Имајте на уму да ће интеракција са видгетом за коментаре на страници са истим urlId-ом једноставно поново креирати Page неприметно.

Пример cURL захтева за уклањање странице

Copy

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

Структура захтева за уклањање странице

Copy

interface PageDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Структура одговора за уклањање странице

Copy

interface PageDeleteResponse {
    status: 'success' | 'failed'
    /** Укључено у случају неуспеха. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'page-does-not-exist'
    /** Укључено у случају неуспеха. **/
    reason?: string
}

Структура чекајућег webhook догађаја

Објекат PendingWebhookEvent представља webhook догађај који је стављен у ред и налази се на чекању.

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
    /** Спољни id који може бити повезан са коментаром. **/
    externalId: string | null
    createdAt: Date
    tenantId: string
    attemptCount: number
    /** Постављено пре првог покушаја, и након сваког неуспеха. **/
    nextAttemptAt: Date
    /** Да ли је ово догађај креирања, брисања или ажурирања... **/
    eventType: OutboundSyncEventType
    /** Тип синхронизације који треба извршити (WordPress, позив API-ја, итд). **/
    type: OutboundSyncType
    /** Домен који се поклапа са коментаром. Користимо овај домен за избор API кључа. **/
    domain: string
    /** Последња грешка која се догодила. Овај тип није типизиран и представља „дамп“ онога што се десило. Обично садржи објекат са statusCode, body, и мапом headers. **/
    lastError: object | null
}

GET /api/v1/pending-webhook-events

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

Ова рута враћа листу очекујућих webhook догађаја у параметру pendingWebhookEvents.

Овај API користи пагинацију, обезбеђену параметром skip. PendingWebhookEvents се враћају страницама по 100, уређеним по createdAt, са најновијим првим.

cURL пример за PendingWebhookEvent

Copy

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

Структура захтева за PendingWebhookEvent

Copy

interface PendingWebhookEventsGetQueryParams {
    tenantId: string
    API_KEY: string
    commentId?: string
    externalId?: string
    eventType?: OutboundSyncEventType
    type?: OutboundSyncType
    domain?: string
    /** Захтев за догађаје који имају број покушаја већи од наведеног. **/
    attemptCountGT?: number
}

Структура одговора за PendingWebhookEvent

Copy

interface PendingWebhookEventsGetResponse {
    status: 'success' | 'failed'
    /** Укључено у случају грешке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Укључено у случају грешке. **/
    reason?: string
    pendingWebhookEvents?: PendingWebhookEvent[]
}

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

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

Ova ruta vraća objekat koji sadrži broj webhook događaja na čekanju u parametru count.

Možete filtrirati pomoću istih parametara kao za endpoint /pending-webhook-events

Primer cURL zahteva za PendingWebhookEvent Count

Copy

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

Struktura zahteva za PendingWebhookEvent Count

Copy

interface PendingWebhookEventsCountQueryParams {
    tenantId: string
    API_KEY: string
    commentId?: string
    externalId?: string
    eventType?: OutboundSyncEventType
    type?: OutboundSyncType
    domain?: string
    /** Upit za događaje čiji je broj pokušaja veći od navedenog. **/
    attemptCountGT?: number
}

Struktura odgovora za PendingWebhookEvent Count

Copy

interface PendingWebhookEventsCountResponse {
    status: 'success' | 'failed'
    /** Uključeno u slučaju greške. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Uključeno u slučaju greške. **/
    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 захтева за брисање 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-у је једноставно као да корисник учита страницу са ажурираним пакетом података.

Међутим, можда ћете желети да управљате корисником ван тог тока, ради побољшања конзистентности ваше апликације.

SSO User API нуди начин за CRUD операције над објектима које називамо SSOUsers. Ови објекти се разликују од редовних Users и држе се одвојено ради типске сигурности.

Структура SSOUser објекта је следећа:

SSOUser Структура

Copy

interface SSOUser {
    id: string
    username: string
    email?: string
    websiteUrl?: string
    signUpDate: number
    createdFromUrlId?: string
    loginCount?: number
    avatarSrc?: string
    optedInNotifications?: boolean
    optedInSubscriptionNotifications?: boolean
    displayLabel?: string
    displayName?: string
    isAccountOwner?: boolean // Администраторска дозвола - SSO корисници са овим флагом се наплаћују као SSO администратори (одвојено од редовних SSO корисника)
    isAdminAdmin?: boolean // Администраторска дозвола - SSO корисници са овим флагом се наплаћују као SSO администратори (одвојено од редовних SSO корисника)
    isCommentModeratorAdmin?: boolean // Модераторска дозвола - SSO корисници са овим флагом се наплаћују као SSO модератори (одвојено од редовних SSO корисника)
    /** Ако је null, Контрола приступа неће бити примењена на корисника. Ако је списак празан, овај корисник неће моћи да види ниједну страницу или да @спомиње друге кориснике. **/
    groupIds?: string[] | null
    createdFromSimpleSSO?: boolean
    /** Не дозвољавајте другим корисницима да виде активност овог корисника, укључујући коментаре, на њиховом профилу. Подразумевано је true како би профили подразумевано били безбедни. **/
    isProfileActivityPrivate?: boolean
    /** Не дозвољавајте другим корисницима да остављају коментаре на профилу корисника, или да виде постојеће коментаре на профилу. Подразумевано false. **/
    isProfileCommentsPrivate?: boolean
    /** Не дозвољавајте другим корисницима да шаљу директне поруке овом кориснику. Подразумевано false. **/
    isProfileDMDisabled?: boolean
    karma?: number
    /** Опционо подешавање за значке корисника. **/
    badgeConfig?: {
        /** Низ ИД-ова значки које се додељују кориснику. Ограничено на 30 значки. Редослед се поштује. **/
        badgeIds: string[]
        /** Ако је true, замењује све постојеће приказане значке са наведеним. Ако је false или изостављено, наведене значке ће се додати постојећима. **/
        override?: boolean
        /** Ако је true, ажурира приказне особине значки из конфигурације закупца. **/
        update?: boolean
    }
}

Наплата за SSO кориснике

SSO корисници се наплаћују различито у зависности од њихових дозвола:

Редовни SSO корисници: Корисници без админ или модераторских дозвола се наплаћују као редовни SSO корисници
SSO администратори: Корисници са isAccountOwner или isAdminAdmin флаговима се наплаћују посебно као SSO администратори (иста цена као редовни администратори закупца)
SSO модератори: Корисници са isCommentModeratorAdmin флагом се наплаћују посебно као SSO модератори (иста цена као редовни модератори)

Важно: Да би се спречило двоструко наплаћивање, систем аутоматски уклања дупликате SSO корисника у односу на редовне tenant кориснике и модераторе по email адреси. Ако SSO корисник има исту email адресу као редовни tenant корисник или модератор, неће бити наплаћени два пута.

Контрола приступа

Корисници се могу груписати у групе. За то служи поље groupIds, и оно је опционo.

@Спомињања

По подразумевaњу, @mentions користе username за претрагу других SSO корисника када се укуца карактер @. Ако је коришћено displayName, резултати који се поклапају са username ће бити занемарени када постоји поклапање за displayName, и резултати претраге за @mention ће користити displayName.

Претплате

У FastComments-у, корисници се могу претплатити на страницу кликом на икону звона у видгету за коментаре и одабиром 'Претплати се'.

Код редовног корисника, шаљемо им мејлове са обавештењима у складу са њиховим подешавањима обавештења.

Код SSO корисника, то је подељено ради назадне компатибилности. Корисници ће добијати додатне мејлове обавештења о претплати само ако поставите optedInSubscriptionNotifications на true.

Значке

Можете доделити значке SSO корисницима користећи својство badgeConfig. Значке су визуелни индикатори који се појављују поред имена корисника у коментарима.

badgeIds - Низ ИД-ова значки које се додељују кориснику. То морају бити валидни ИД-ови значки креирани на вашем FastComments налогу. Ограничено на 30 значки.
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 корисника на основу њиховог имејла.

SSOUser по имејлу - пример cURL

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 захтева за ажурирање SSO корисника

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

Структура захтева за ажурирање SSO корисника

Copy

interface SSOUserPatchQueryParams {
    tenantId: string
    API_KEY: string
    /** Када се промени email или username, можете поставити ово на true да бисте такође ажурирали корисникове коментаре. Ово ће удвостручити трошак кредита. **/
    updateComments: 'true' | 'false'
}

Структура одговора за ажурирање SSO корисника

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-јем ће резултирати грешком.

SSOUser креирање — пример cURL захтева

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-ја могу се преписати једноставним слањем другог HMAC payload-а за SSO корисника. На пример, ако поставите 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 захтева за ажурирање SSO корисника

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 за контролу приступа, али ово је опционално.

Структура захтева за ажурирање SSO корисника

Copy

interface SSOUserPutQueryParams {
    tenantId: string
    API_KEY: string
    /** Када се мења имејл или корисничко име, можете поставити ово на true да бисте такође ажурирали коментаре корисника. Ово ће удвостручити трошкове у кредитима. **/
    updateComments: 'true' | 'false'
}

Структура одговора за ажурирање SSO корисника

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 query параметра. Имајте у виду да ако је ово true:

Сви корисникови коментари биће обрисани уживо.
Сви child (сада сирочад) коментари биће обрисани или анонимизовани у зависности од конфигурације странице повезане са сваким коментаром. На пример, ако је режим брисања нити "anonymize", онда одговори остају, а корисникови коментари ће бити анонимизовани. Ово се примењује само када је commentDeleteMode Remove (подразумевана вредност).
creditsCost постаје 2.

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

Можете задржати корисникове коментаре али их једноставно анонимизовати постављањем commentDeleteMode=1.

Ако су корисникови коментари анонимизовани онда следеће вредности се постављају на null:

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

isDeleted и isDeletedUser се постављају на true.

При рендеровању, видгет коментара ће за име корисника користити DELETED_USER_PLACEHOLDER (подразумевано: "[deleted]") и DELETED_CONTENT_PLACEHOLDER за сам коментар. Ово се може прилагодити преко корисничког интерфејса за прилагођавање видгета.

Примери

Пример cURL захтева за уклањање SSO корисника

Copy

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

Структура захтева за уклањање SSO корисника

Copy

enum SSOUserCommentDeleteMode {
    Remove = 0, // подразумевано
    Anonymize = 1
}
interface SSOUsersDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** You can set this to true to also delete the user's comments. This will double the credit cost. **/
    deleteComments?: 'true' | 'false'
    /** You can set this as desired to determine how to handle the user's comments. **/
    commentDeleteMode?: SSOUserCommentDeleteMode
}

Структура одговора за уклањање SSO корисника

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; // На успех враћамо уклоњеног корисника.
}

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

Objekat Subscription predstavlja pretplatu za korisnika.

Subscription objekti se kreiraju kada korisnik klikne na zvonce za obaveštenja u widgetu za komentare i klikne "Subscribe to this page".

Pretplate se takođe mogu kreirati putem API-ja.

Imanje objekta Subscription uzrokuje kreiranje objekata Notification i slanje emailova kada se ostave novi komentari na korenu povezane stranice za koju je ta Subscription. Slanje emailova zavisi od tipa korisnika. Za obične korisnike to zavisi od optedInNotifications. Za SSO korisnike to zavisi od optedInSubscriptionNotifications. Imajte na umu da neke aplikacije možda nemaju koncept web-pristupačne stranice, u kom slučaju jednostavno postavite urlId na id stavke na koju se pretplaćujete (ista vrednost za urlId koju biste prosledili widgetu za komentare).

Struktura za objekat Subscription je sledeća:

Struktura objekta Subscription

Copy

interface Subscription {
    id: string
    tenantId: string
    /** Sa SSO-om, korisnički id je u formatu `<tenant id>:<user id>`. **/
    userId: string
    anonUserId?: string
    urlId: string
    url?: string
    pageTitle?: string
    createdAt: string // string datuma
}

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 POST захтева за Subscription

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 захтева за Subscription

Copy

interface SubscriptionPostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура POST одговора за Subscription

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

Ова рута омогућава претрагу коришћења tenant-а по години, месецу и дану. Може се вратити до 365 објеката, а трошак је 1 API кредит на сваких 10 објеката.

Објекти одговора су сортирани по датуму када су креирани (најстарији први).

Пример cURL претраге TenantDailyUsage

Copy

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

Структура захтева TenantDailyUsage

Copy

interface TenantDailyUsageQueryParams {
    tenantId: string
    API_KEY: string
    /** На основу UTC. **/
    yearNumber?: number
    /** Нула-базирано. На основу UTC. **/
    monthNumber?: number
    /** Почиње од 1. На основу UTC. **/
    dayNumber?: number
}

Структура одговора TenantDailyUsage

Copy

interface TenantDailyUsageResponse {
    status: 'success' | 'failed'
    /** Укључено у случају неуспеха. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Укључено у случају неуспеха. **/
    reason?: string
    tenantDailyUsages: TenantDailyUsage[]
}

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

Tenant дефинише корисника FastComments.com. Они се могу креирати преко API-ја од стране tenant-ова који имају приступ за white labeling. White labeled tenants cannot create other white labeled tenants (only one level of nesting is allowed).

Структура објекта Tenant је следећа:

Структура Tenant-а

Copy

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

Пагинација се обезбеђује помоћу query параметра skip. Tenant-ови се враћају по страницама од 100, уређени по signUpDate и id.

Трошак зависи од броја враћених tenant-ова; кошта 1 credit per 10 враћених tenant-ова.

Пример cURL захтева за Tenant

Copy

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

Можете дефинисати meta параметре на Tenant објектима и извршити упит за одговарајуће tenant-ове. На пример, за кључ someKey и meta вредност some-value, можемо конструисати JSON објекат са овим паром кључ/вредност и затим га URI-кодирати као query параметар да бисмо филтрирали:

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

Ovaj ruta omogućava dodavanje jednog Tenant.

Kreiranje Tenant ima sledeća ograničenja:

name je obavezno.
domainConfiguration je obavezno.
Sledeće vrednosti ne smeju biti prosleđene prilikom kreiranja Tenant:
- hasFlexPricing
- lastBillingIssueReminderDate
- flexLastBilledAmount
signUpDate ne sme da bude u budućnosti.
name ne sme biti duže od 200 characters.
email ne sme biti duži od 300 characters.
email mora biti jedinstven za sve FastComments.com tenante.
Ne možete kreirati tenante ako roditeljski tenant nema definisan validan TenantPackage.
- Ako je vaš tenant kreiran putem FastComments.com, ovo ne bi trebalo da predstavlja problem.
Ne možete kreirati više tenant-a nego što je definisano u maxWhiteLabeledTenants u vašem paketu.
Morate navesti query parametar tenantId koji je id vašeg parent tenant sa uključenim white labeling-om.

Možemo kreirati Tenant sa samo nekoliko parametara:

Primer cURL zahteva za kreiranje Tenant-a

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

Struktura zahteva za kreiranje Tenant-a

Copy

interface TenantPostQueryParams {
    tenantId: string
    API_KEY: string
}

Struktura odgovora za kreiranje Tenant-a

Copy

interface TenantPostResponse {
    status: 'success' | 'failed'
    /** Uključeno u slučaju neuspeha. **/
    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'
    /** Uključeno u slučaju neuspeha. **/
    reason?: string
    tenant?: Tenant; // Vraćamo kompletan kreirani tenant pri uspehu.
}

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 tenant-има.
Када се постави billingInfoValid на true, billingInfo мора бити послат у истом захтеву.
Не можете ажурирати packageId повезан са вашим сопственим tenant-ом.
Не можете ажурирати paymentFrequency повезан са вашим сопственим tenant-ом.

Пример cURL захтева за Tenant PATCH

Copy

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

Структура захтева за Tenant PATCH

Copy

interface TenantPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Структура одговора за Tenant PATCH

Copy

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

DELETE /api/v1/tenants/:id

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

Ова рута омогућава уклањање Tenant и свих повезаних података (корисника, коментара итд.) по id.

Постоје следећа ограничења приликом уклањања tenant-ова:

Tenant мора бити ваш, или white labeled tenant којим управљате.
Параметар упита sure мора бити подешен на true.

Пример cURL захтева за уклањање Tenant-а

Copy

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

Структура захтева за уклањање Tenant-а

Copy

interface TenantDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Структура одговора при уклањању Tenant-а

Copy

interface TenantDeleteResponse {
    status: 'success' | 'failed'
    /** Укључено у случају неуспеха. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized' | 'unsure'
    /** Укључено у случају неуспеха. **/
    reason?: string
}

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

The TenantPackage дефинише информације о пакету доступном Tenant-у. Тенант може имати више доступних пакета, али само један може бити активан у датом тренутку.

Tenant не може да се користи за било које производе док његов packageId не показује на важећи TenantPackage.

Постоје два типа TenantPackage објеката:

Пакети са фиксном ценом - где је hasFlexPricing false.
Флексибилно ценообразовање - где је hasFlexPricing true.

У оба случаја лимити се дефинишу на налогу који користи пакет, међутим са Flex моделом тенант се наплаћује основна цена плус оно што је користио, дефинисано flex* параметрима.

Тенант може имати више tenant пакета и има могућност да сам промени пакет са странице Billing Info Page.

Ако ћете сами управљати наплатом за тенанте, и даље ћете морати да дефинишете пакет за сваког тенанта како бисте одредили њихове лимите. Једноставно подесите billingHandledExternally на true на 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

Ovaj endpoint vraća jedan Tenant Package po id-u.

TenantPackage cURL primer po ID-u

Copy

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

Struktura zahteva TenantPackage

Copy

interface TenantPackageByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Struktura odgovora TenantPackage

Copy

interface TenantPackageByIdResponse {
    status: 'success' | 'failed'
    /** Uključeno u slučaju neuspeha. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Uključeno u slučaju neuspeha. **/
    reason?: string
    tenantPackage: TenantPackage
}

GET /api/v1/tenant-packages

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

Ovaj API koristi paginaciju, koja se obezbeđuje parametrom upita skip. TenantPackages se vraćaju u stranicama po 100, poredane po createdAt i id.

Cena se zasniva na broju vraćenih tenant paketa, koštajući 1 credit per 10 vraćenih tenant paketa.

Primer cURL zahteva za TenantPackage

Copy

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

Struktura zahteva za TenantPackage

Copy

interface TenantPackagesRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** Broj tenant paketa koje treba preskočiti za paginaciju. **/
    skip?: number
}

Struktura odgovora za TenantPackage

Copy

interface TenantPackagesResponse {
    status: 'success' | 'failed'
    /** Uključeno u slučaju neuspeha. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Uključeno u slučaju neuspeha. **/
    reason?: string
    tenantPackages?: TenantPackage[]
}

POST /api/v1/tenant-packages

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

Ова рута омогућава додавање једног TenantPackage.

Креирање TenantPackage има следећа ограничења:

Следећи параметри су обавезни:
- name
- tenantId
- monthlyCostUSD - Може бити null.
- yearlyCostUSD - Може бити null.
- maxMonthlyPageLoads
- maxMonthlyAPICredits
- maxMonthlyComments
- maxConcurrentUsers
- maxTenantUsers
- maxSSOUsers
- maxModerators
- maxDomains
- hasDebranding
- forWhoText
- featureTaglines
- hasFlexPricing - Ако је true, онда су сви flex* параметри обавезни.
name не може бити дужи од 50 characters.
Сваки елемент forWhoText не може бити дужи од 200 characters.
Сваки елемент featureTaglines не може бити дужи од 100 characters.
TenantPackage мора бити "smaller" од родитељског тенанта. На пример, сви max* параметри морају имати ниже вредности од родитељског тенанта.
Тенант са белим брендирањем може имати највише пет пакета.
Само тенанти са приступом белом брендирању могу креирати TenantPackage.
Не можете додавати пакете свом сопственом тенанту. :)

Можемо креирати TenantPackage на следећи начин:

TenantPackage креирање путем е-поште - пример cURL

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

Ovaj API endpoint omogućava ažuriranje TenantPackage pomoću id.

Ažuriranje TenantPackage ima sledeća ograničenja:

Ako postavite hasFlexPricing na true, onda su svi flex* parametri obavezni u istom zahtevu.
name ne može biti duži od 50 characters.
Svaka stavka forWhoText ne može biti duža od 200 characters.
Svaka stavka featureTaglines ne može biti duža od 100 characters.
TenantPackage mora biti "manji" od nadređenog tenanta. Na primer, svi max* parametri moraju imati niže vrednosti od nadređenog tenanta.
Ne možete promeniti tenantId povezan sa TenantPackage.

TenantPackage PATCH cURL Primer

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

Struktura PATCH zahteva za TenantPackage

Copy

interface TenantPackagePatchQueryParams {
    tenantId: string
    API_KEY: string
}

Struktura odgovora za TenantPackage PATCH

Copy

interface TenantPackagePatchResponse {
    status: 'success' | 'failed'
    /** Uključeno u slučaju neuspeha. **/
    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'; 
    /** Uključeno u slučaju neuspeha. **/
    reason?: string
}

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

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

Ова рута омогућава уклањање TenantPackage по id.

Не можете уклонити TenantPackage који је у употреби (а tenant-ов packageId указује на пакет). Прво ажурирајте Tenant.

Пример cURL захтева за уклањање TenantPackage

Copy

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

Структура захтева за уклањање TenantPackage

Copy

interface TenantPackageDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Структура одговора за уклањање TenantPackage

Copy

interface TenantPackageDeleteResponse {
    status: 'success' | 'failed'
    /** Укључено у случају неуспеха. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized' | 'package-in-use'
    /** Укључено у случају неуспеха. **/
    reason?: string
}

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

TenantUser definiše User koji je upravljan od strane određenog Tenant. Njihov nalog se u potpunosti nalazi pod kontrolom Tenant sa kojim su povezani, i njihov nalog može biti ažuriran ili izbrisan putem UI ili API.

Tenant korisnici mogu biti administratori sa svim dozvolama i pristupom Tenant, ili mogu biti ograničeni na određene dozvole za moderisanje komentara, pristup API ključevima itd.

Struktura za TenantUser objekat je sledeća:

Struktura TenantUser objekta

Copy

/** Ovo je za obaveštenja. **/
export enum UserDigestEmailFrequency {
    Disabled = -1,
    Daily = 0,
    Weekly = 1,
    Monthly = 2
}
export interface TenantUser {
    id: string
    tenantId: string
    username: string
    /** Na primer, link ka blogu komentatora. **/
    websiteUrl?: string
    email: string
    signUpDate: number
    createdFromUrlId: string
    createdFromTenantId: string
    verified: boolean
    loginCount: number
    optedInNotifications: boolean
    optedInTenantNotifications: boolean
    hideAccountCode: boolean
    avatarSrc?: string
    /** Da li korisnik prima zahteve za pomoć od komentatora? **/
    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.

TenantUser по ID — cURL пример

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 query параметра. TenantUsers се враћају у страницама по 100, сортирани по signUpDate, username и id.

Трошак зависи од броја враћених TenantUsers: 1 credit per 10 враћених TenantUsers.

Пример 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
    /** Број TenantUsers које треба прескочити за пагинацију. **/
    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 уместо тога.
Не можете креирати више tenant корисника него што је дефинисано под 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

This route provides the ability to send a login link to a single TenantUser.

Useful when batch creating users and not having to instruct them on how to login to FastComments.com. This will just send them a "magic link" to login that expires after 30 days.

The following restrictions exist to send a login link to a TenantUser:

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

We can send a login link to a TenantUser as follows:

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

Ovaj endpoint pruža mogućnost ažuriranja jednog TenantUser.

Ažuriranje TenantUser ima sledeća ograničenja:

signUpDate ne sme biti u budućnosti.
locale mora biti na listi Podržani lokaliteti.
username mora biti jedinstveno na celom FastComments.com. Ako je to problem, preporučujemo korišćenje SSO umesto toga.
email mora biti jedinstven na celom FastComments.com. Ako je to problem, preporučujemo korišćenje SSO umesto toga.
Ne možete ažurirati tenantId korisnika.

Možemo ažurirati TenantUser na sledeći način

Primer cURL zahteva za ažuriranje 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"
}'

Struktura zahteva za ažuriranje TenantUser

Copy

interface TenantUserPatchQueryParams {
    tenantId: string
    API_KEY: string
    /** Kada se promeni email ili username, možete ovo postaviti na true da biste takođe ažurirali komentare korisnika. Ovo će udvostručiti trošak kredita. **/
    updateComments: 'true' | 'false'
}

Struktura odgovora za ažuriranje TenantUser

Copy

interface TenantUserPatchResponse {
    status: 'success' | 'failed'
    /** Uključeno u slučaju neuspeha. **/
    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'
    /** Uključeno u slučaju neuspeha. **/
    reason?: string
}

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

Resource: TenantUser as DELETE /api/v1/tenant-users/:id Credit Cost: 5

Ова рута омогућава уклањање TenantUser по id.

Брисање корисникових коментара је могуће помоћу query параметра deleteComments. Имајте на уму да ако је ово тачно:

Сви корисникови коментари биће одмах обрисани.
Сви 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 за коментар. Ово се може прилагодити преко UI за прилагођавање виџета.

Примери

Пример cURL захтева за уклањање TenantUser

Copy

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

Структура захтева за уклањање TenantUser

Copy

enum TenantUserCommentDeleteMode {
    Remove = 0, // подразумевано
    Anonymize = 1
}
interface TenantUserDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** Можете поставити ово на true да бисте такође избрисали корисничке коментаре. Ово ће удвостручити трошак у кредитима. **/
    deleteComments?: 'true' | 'false'
    /** Ово можете подесити по жељи да одредите како поступати са корисничким коментарима. **/
    commentDeleteMode?: TenantUserCommentDeleteMode
}

Структура одговора за уклањање TenantUser

Copy

interface TenantUserDeleteResponse {
    status: 'success' | 'failed'
    /** Укључено у случају неуспеха. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized'
    /** Укључено у случају неуспеха. **/
    reason?: string
}

Структура корисника

User је објекат који представља најчешћи именитељ свих корисника.

Имајте на уму да у FastComments имамо низ различитих случајева употребе за кориснике:

Secure SSO
Simple SSO
Tenant Users (На пример: Administrators)
Commenters

Овај API је за Commenters и кориснике креиране путем Simple SSO. У основи, сваки корисник креиран преко вашег сајта може се приступити преко овог API-ја. Tenant Users се такође могу преузети на овај начин, али ћете добити више информација интеракцијом са /tenant-users/ API-јем.

За Secure SSO користите /sso-users/ API.

Не можете ажурирати ове типове корисника. Они су креирали налог преко вашег сајта, тако да пружамо основни приступ само за читање, али не можете вршити измене. Ако желите да имате овакав ток - потребно је да подесите Secure SSO.

Структура за User објекат је следећа:

Структура објекта User

Copy

export interface User {
    /** Ово је такође id који се користи као userId на comment објектима. **/
    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

Ова рута враћа једног корисника по ID.

Пример cURL захтева за корисника по ID

Copy

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

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

Copy

interface UserByIdQueryParams {
    tenantId: string
    API_KEY: string
}

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

Copy

interface UserByIdResponse {
    status: 'success' | 'failed'
    /** Укључено у случају неуспеха. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'unauthorized'
    /** Укључено у случају неуспеха. **/
    reason?: string
    user?: User
}

Структура гласа

Објекат Vote представља глас који је оставио корисник.

Однос између коментара и гласа дефинисан је преко commentId.

Структура објекта Vote је следећа:

Структура Vote

Copy

interface Vote {
    id: string
    urlId: string
    commentId: string
    userId: string
    direction: 1 | -1
    createdAt: string
}

GET /api/v1/votes

Resource: Vote as GET /api/v1/votes Credit Cost: 10

Гласови морају бити преузети по urlId.

Врсте гласова

Постоје три врсте гласова:

Аутентификовани гласови, који се примењују на одговарајући коментар. Можете их креирати помоћу овог API-ја.
Аутентификовани гласови, који су у стању на чекању за верификацију, и стога још нису примењени на коментар. Ови се креирају када корисник користи FastComments.com login to vote механизам.
Анонимни гласови, који се примењују на одговарајући коментар. Ови се креирају заједно са анонимним коментарисањем.

Они се у API-ју враћају у одвојеним списковима ради смањења забуне.

Пример cURL захтева за гласове

Copy

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

Структура захтева за гласове

Copy

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

Структура одговора за гласове

Copy

interface VotesResponse {
    status: 'success' | 'failed'
    /** Укључено у случају неуспеха. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id'
    /** Укључено у случају неуспеха. **/
    reason?: string
    /** Овлашћени, верификовани гласови, примењени на одговарајуће коментаре. **/
    appliedAuthorizedVotes: Vote[]
    /** Анонимни гласови, примењени на одговарајуће коментаре. **/
    appliedAnonymousVotes: Vote[]
    /** Гласови на чекању верификације, још нису примењени на одговарајуће коментаре. **/
    pendingVotes: Vote[]
}

Напомене о анонимним гласовима

Имајте на уму да ће анонимни гласови креирани преко овог API-ја појавити у списку appliedAuthorizedVotes. Сматрају се овлашћеним јер су креирани преко API-ја помоћу API кључа.

Структура appliedAnonymousVotes је за гласове креиране без е-поште, API кључа итд.

GET /api/v1/votes/for-user

Resource: Vote as GET /api/v1/votes/for-user Credit Cost: 1

Омогућава преузимање гласова које је оставио корисник за одређени urlId. Прима userId који може бити било који FastComments.com корисник или SSO User.

Ово је корисно ако желите да прикажете да ли је корисник гласао за коментар. При преузимању коментара, једноставно позовите овај API истовремено за тог корисника са истим urlId.

Ако користите анонимно гласање, онда треба да проследите anonUserId уместо тога.

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

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/votes/for-user?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=test&userId=some-user-id'

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

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/votes/for-user?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=test&anonUserId=some-user-id'

Имајте у виду да ће анонимни гласови бити приказани у листи appliedAuthorizedVotes. Они се сматрају овлашћеним јер су креирани путем API-ја са API key-ом.

Структура захтева за гласове корисника

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
}

Крeирање анонимних гласова

Анонимни гласови се могу креирати постављањем anonUserId у query параметрима уместо userId.

Овај id не мора да одговара објекту корисника нигде (отуда анониман). Он је једноставно идентификатор за сесију, тако да можете поново преузети гласове у истој сесији, да бисте проверавали да ли је коментар гласан.

Ако немате такву ствар као „анонимне сесије“ као што FastComments има — можете једноставно поставити ово на случајни ID, као што је UUID (иако ценимо мање идентификаторе ради уштеде простора).

Друге напомене

Овај API поштује поставке на нивоу tenant-а. На пример, ако онемогућите гласање за одређену страницу, и покушате да креирате глас преко API-ја, то ће не успети са кодом грешке voting-disabled.
Овај API је подразумевано live.
Овај API ће ажурирати votes одговарајућег Comment.

DELETE /api/v1/votes/:id

Resource: Vote as DELETE /api/v1/votes/:id Credit Cost: 1

Ова рута омогућава брисање појединачног Vote.

Пример cURL захтева за брисање Vote

Copy

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

Структура захтева за брисање Vote

Copy

interface VoteDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Структура одговора за брисање Vote

Copy

interface VoteDeleteResponse {
    status: 'success' | 'failed'
    /** Укључено у случају неуспеха. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id'
    /** Укључено у случају неуспеха. **/
    reason?: string
}

Напомене:

Овај API поштује подешавања на нивоу tenant-а. На пример, ако онемогућите гласање за одређену страницу, и покушате да преко API-ја креирате глас, то ће пропасти са кодом грешке voting-disabled.
Овај API је по подразумеву активан.
Овај API ће ажурирати votes одговарајућег Comment.

Структура конфигурације домена

A DomainConfig object represents configuration for a domain for a tenant.

The structure for the DomainConfig object is as follows:

Структура конфигурације домена

Copy

interface DomainConfig {
    /** Домен, не URL, као што је "fastcomments.com" или "www.example.com". Поддомен може бити укључен ако желите ограничити на поддомен. Максимално 1000 карактера. **/
    domain: string
    /** Име пошиљаоца које се користи при слању имејлова. **/
    emailFromName?: string
    /** From-Email који се користи при слању имејлова. Осигурајте да је SPF подешен да омогући mail.fastcomments.com да шаље имејлове у име домена који се користи у овом атрибуту. **/
    emailFromEmail?: string
    /** Само за читање. Када је објекат креиран. **/
    createdAt: string
    /** Лого везан за овај домен. Користи се у имејловима. Користите HTTPS. **/
    logoSrc?: string
    /** Мањи лого везан за овај домен. Користите HTTPS. **/
    logoSrc100px?: string
    /** Само за SSO. URL који се користи у фоотеру сваког послатог имејла. Подржава променљиву "[userId]". **/
    footerUnsubscribeURL?: string
    /** Само за SSO. Хедери који се користе у сваком послатом имејлу. Корисно, на пример, за подешавање хедера везаних за отписивање ради побољшања испоруке. Ставка List-Unsubscribe у овом запису, ако постоји, подржава променљиву "[userId]". **/
    emailHeaders?: Record<string, string>
    /** Онемогући све линкове за отписивање. Није препоручљиво, може негативно утицати на стопе испоруке. **/
    disableUnsubscribeLinks?: boolean
    /** DKIM конфигурација. **/
    dkim?: DomainConfigDKIM
}

Структура DKIM конфигурације

Copy

interface DomainConfigDKIM {
    /** Име домена у вашем DKIM запису. **/
    domainName: string
    /** Селектор DKIM кључа који треба користити. **/
    keySelector: string
    /** Ваш приватни кључ. Почните са -----BEGIN PRIVATE KEY----- и завршите са -----END PRIVATE KEY----- **/
    privateKey: string
}

За аутентификацију

Конфигурација домена се користи да одреди који сајтови могу угостити FastComments видгет за ваш налог. Ово је основни облик аутентификације, што значи да додавање или уклањање било којих конфигурација домена може утицати на доступност ваше FastComments инсталације у продукцији.

Не уклањајте или мењајте својство domain у Domain Config за домен који се тренутно користи осим ако заиста не намеравате да онемогућите тај домен.

Ово има исто понашање као уклањање домена из /auth/my-account/configure-domains.

Такође имајте у виду да ће уклањање домена из интерфејса My Domains уклонити и сваку одговарајућу конфигурацију за тај домен која је можда додата преко тог интерфејса.

За прилагођавање имејлова

Линк за отписивање у фоотеру имејла, и функција једним кликом за отписивање коју нуде многи имејл клијенти, могу се подесити преко овог API-ја дефинисањем footerUnsubscribeURL и emailHeaders, респективно.

За DKIM

Након дефинисања ваших DKIM DNS записа, једноставно ажурирајте DomainConfig са вашом DKIM конфигурацијом користећи дефинисану структуру.

GET /api/v1/domain-configs

Resource: Comment as GET /api/v1/domain-configs Credit Cost: 1

Овај API омогућава преузимање свих DomainConfig објеката за тенанта.

Пример cURL за DomainConfig GET

Copy

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

Структура GET захтева за DomainConfig

Copy

interface GetDomainConfigsRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Структура GET одговора за DomainConfig

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

Pojedinačni DomainConfigs mogu se dohvatiti pomoću odgovarajućeg domain.

Primer cURL zahteva za Domain Config po domenu

Copy

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

Struktura zahteva za Domain Config po domenu

Copy

interface DomainConfigsByDomainRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Struktura odgovora za Domain Config po domenu

Copy

interface DomainConfigResponse {
    status: 'success' | 'failed'
    /** Uključeno u slučaju neuspeha. **/
    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'
    /** Uključeno u slučaju neuspeha. **/
    reason?: string
    configuration?: DomainConfig | null
}

POST /api/v1/domain-configs

Resource: DomainConfig as POST /api/v1/domain-configs Credit Cost: 1

Овај API крајњи пут омогућава креирање конфигурација домена.

Додавање конфигурације за домен овлашћује тај домен за FastComments налог.

Уобичајене употребе овог API-ја су почетно подешавање, када се жели додати више домена, или прилагођене конфигурације за слање имејлова.

DomainConfig POST cURL пример

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-ја омогућава ажурирање конфигурације домена навођењем само домена и атрибута који треба ажурирати.

DomainConfig PATCH cURL пример

Copy

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

DomainConfig PATCH структура захтева

Copy

interface DomainConfigPatchQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig PATCH структура одговора

Copy

interface DomainConfigPatchResponse {
    status: 'success' | 'failed'
    /** Укључено у случају неуспеха. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'missing-domain' | 'domain-does-not-exist' | 'update-would-create-duplicate' | 'domain-too-long' | 'domain-invalid';  
    /** Укључено у случају неуспеха. **/
    reason?: string
    /** Ажурирана конфигурација. **/
    configuration?: DomainConfig
}

PUT /api/v1/domain-configs/:domain

Resource: DomainConfig as PUT /api/v1/domain-configs/:domain Credit Cost: 1

Овај API endpoint омогућава замену конфигурације домена.

Пример 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-а.
Напомена: Поновно додавање домене преко UI-ја ће поново креирати објекат (са само попуњеним пољем domain).

Пример cURL захтева за уклањање DomainConfig-а

Copy

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

Структура захтева за уклањање DomainConfig-а

Copy

interface DomainConfigRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Структура одговора за уклањање DomainConfig-а

Copy

interface DomainConfigDeleteResponse {
    status: 'success' | 'failed'
    /** Укључено у случају неуспеха. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-domain' | 'domain-config-does-not-exist'
    /** Укључено у случају неуспеха. **/
    reason?: string
}

Структура конфигурације питања

FastComments пружа начин за конструкцију питања и агрегирање њихових резултата. Пример питања (даље названо QuestionConfig) може бити оцена у звездицама, клизач, или NPS питање (одређено преко type).

Подаци о питањима могу се агрегирати појединачно, заједно, током времена, укупно, по страници и слично.

Овај фрејмворк има све могућности потребне за израду клијентских виџета (са вашим сервером испред овог API-ја), администраторских контролних панела и алата за извештавање.

Прво морамо дефинисати QuestionConfig. Структура је следећа:

Структура QuestionConfig

Copy

type QuestionConfigType = 'nps' | 'slider' | 'star' | 'thumbs';
interface QuestionConfig {
    id: string
    tenantId: string
    name: string
    question: string
    helpText?: string
    createdAt: string
    createdBy: string
    /** САМО ЗА ЧИТАЊЕ - повећава се за сваки нови одговор. **/
    usedCount: number
    /** Стринг који представља датум када је конфигурација последњи пут коришћена (остављен резултат). **/
    lastUsed?: string
    type: QuestionConfigType
    numStars?: number
    min?: number
    max?: number
    defaultValue?: number
    labelNegative?: string
    labelPositive?: string
    subQuestionIds?: string[]
    alwaysShowSubQuestions?: boolean
    reportingOrder: number
}

GET /api/v1/question-configs

Resource: QuestionConfig as GET /api/v1/question-configs Credit Cost: 1

Ova ruta vraća do 100 QuestionConfig objekata odjednom, paginirano. Trošak је 1 за svaka 100 objekata. Sortirani su по тексту питања узлазно (question field).

Primer QuestionConfig

Copy

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

Struktura zahteva QuestionConfig

Copy

interface QuestionConfigRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
    /** За пагинацију. Почinje од 0. **/
    skip?: number
}

Struktura odgovora QuestionConfig

Copy

interface QuestionConfigByIdResponse {
    status: 'success' | 'failed'
    /** Укључено у случају неуспеха. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Укључено у случају неуспеха. **/
    reason?: string
    questionConfigs: QuestionConfig[]
}

GET /api/v1/question-configs/:id

Resource: QuestionConfig as GET /api/v1/question-configs/:id Credit Cost: 1

Ова рута враћа један QuestionConfig по његовом id-у.

Пример cURL захтева за QuestionConfig по ID

Copy

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

Структура захтева за QuestionConfig

Copy

interface QuestionConfigRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Структура одговора за QuestionConfig

Copy

interface QuestionConfigByIdResponse {
    status: 'success' | 'failed'
    /** Укључено у случају неуспеха. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Укључено у случају неуспеха. **/
    reason?: string
    questionConfig?: QuestionConfig
}

POST /api/v1/question-configs

Resource: QuestionConfig as POST /api/v1/question-configs Credit Cost: 1

Овај API ендпоинт омогућава креирање QuestionConfig.

QuestionConfig POST cURL Пример

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/question-configs?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some name that shows on reports.",
    "question": "how much do you like this api?",
    "type": 'slider',
    "reportingOrder": 0,
    "min": 0,
    "max": 10
}'

QuestionConfig POST Структура захтева

Copy

interface QuestionConfigPostQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionConfig POST Структура одговора

Copy

interface QuestionConfigPostResponse {
    status: 'success' | 'failed'
    /** Укључено у случају неуспеха. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input';  
    /** Укључено у случају неуспеха. **/
    reason?: string
    /** Креирани објекат. **/
    questionConfig?: QuestionConfig
}

PATCH /api/v1/question-configs/:id

Resource: QuestionConfig as PATCH /api/v1/question-configs/:id Credit Cost: 1

Ова рута омогућава ажурирање једног QuestionConfig.

Следећа структура представља све вредности које се могу променити:

Структура QuestionConfig

Copy

interface QuestionConfigPatchBody {
    name?: string
    question?: string
    helpText?: string
    /** Упозорење! Промена type-а може пореметити извештавање ако су min/max различити. **/
    type?: QuestionConfigType
    numStars?: number
    min?: number
    max?: number
    defaultValue?: number
    labelNegative?: string
    labelPositive?: string
    subQuestionIds?: string[]
    alwaysShowSubQuestions?: boolean
    reportingOrder?: number
}

cURL пример ажурирања QuestionConfig

Copy

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

Структура захтева за ажурирање QuestionConfig

Copy

interface QuestionConfigPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Структура одговора за ажурирање QuestionConfig

Copy

interface QuestionConfigPatchResponse {
    status: 'success' | 'failed'
    /** Укључено у случају неуспеха. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'unauthorized' | 'missing-api-key' | 'missing-id' | 'not-found' | 'empty-request' | 'invalid-input'
    /** Укључено у случају неуспеха. **/
    reason?: string
}

DELETE /api/v1/question-configs/:id

Resource: QuestionConfig as DELETE /api/v1/question-configs/:id Credit Cost: 100

Ова рута омогућава уклањање QuestionConfig по id-у.

Ово ће обрисати све одговарајуће резултате питања (али не и коментаре). Ово је део високог трошка кредита.

Пример cURL захтева за уклањање QuestionConfig

Copy

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

Структура захтева за уклањање QuestionConfig

Copy

interface QuestionConfigDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Структура одговора за уклањање QuestionConfig

Copy

interface QuestionConfigResponse {
    status: 'success' | 'failed'
    /** Укључено у случају грешке. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Укључено у случају грешке. **/
    reason?: string
}

Структура резултата питања

Да бисте сачували резултате за питања, креирате QuestionResult. Потом можете агрегирати резултате питања, и такође их повезати са коментарима у сврху извештавања.

Структура QuestionResult

Copy

interface QuestionResultMeta {
    name: string
    values: string[]
}
interface QuestionResult {
    id: string
    tenantId: string
    urlId: string
    anonUserId?: string
    userId?: string
    createdAt?: string
    value: number
    commentId?: string
    questionId: string
    meta?: QuestionResultMeta[]
}

GET /api/v1/question-results

Resource: QuestionResults as GET /api/v1/question-results Credit Cost: 1

Ова рута враћа до 1000 QuestionResults објеката одједном, пагинирано. Цена је 1 за сваких 100 објеката. Они су сређени по createdAt, растуће. Можете филтрирати по разним параметрима.

Пример QuestionResults

Copy

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

Структура захтева QuestionResults

Copy

interface QuestionResultsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** За пагинацију. Почиње од 0. **/
    skip?: number
    /** За пагинацију. **/
    limit?: number
    /** Добијте резултате са одређене странице. **/
    urlId?: string
    /** Добијте резултате од одређеног корисника. **/
    userId?: string
    startDate?: string | number
    questionId?: string | string[]
}

Структура одговора QuestionResults

Copy

interface QuestionResultsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    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"]
        }
    ]
}'

Структура захтева за QuestionResult (POST)

Copy

interface QuestionResultPostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура одговора за QuestionResult (POST)

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

Ovde se vrši agregacija rezultata.

Struktura odgovora agregacije je sledeća:

Struktura QuestionResultsAggregationResult

Copy

interface QuestionResultDataPoint {
    /** Mapa vrednosti na broj pojavljivanja te vrednosti za trenutnu tačku podataka (vremenski bucket ili stranica). **/
    v: Map<ValueAsString, number>
    total: number
}
interface QuestionResultsAggregationResult {
    /** Napomena - null je kada timeBucket nije naveden. **/
    dataByDateBucket?: Map<DateString, QuestionResultDataPoint>
    dataByUrlId?: Map<URLIdString, QuestionResultDataPoint>
    countsByValue?: Map<ValueAsString, number>
    /** Ukupan broj agregiranih rezultata. **/
    total: number
    /** Dobijeni ponderisani prosek. To je decimalni broj (float), obično sa dve decimale ili manje. **/
    average: number
    /** Datum u obliku stringa koji predstavlja kada su ovi podaci izračunati, jer mogu doći iz keša. **/
    createdAt: string
}

Evo parametara upita dostupnih za agregaciju:

Struktura zahteva QuestionResultsAggregation

Copy

interface QuestionResultsAggregateRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** Možete agregirati rezultate za jedno ili više pitanja. **/
    questionId: string | string[]
    startDate?: string | number
    timeBucket?: 'day' | 'month' | 'year'
    /** Agregiraj za određenu stranicu. **/
    urlId?: string
    /** Agregiraj za određenog korisnika. **/
    userId?: string
    /** Forsiraj ponovno izračunavanje odmah i ažuriraj keš. **/
    forceRecalculate?: boolean
}

Evo primera zahteva:

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

Primer odgovora:

Primer odgovora 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
    }

Struktura odgovora QuestionResultsAggregation

Copy

interface QuestionResultsAggregationResponse {
    status: 'success' | 'failed'
    /** Uključeno u slučaju greške. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Uključeno u slučaju greške. **/
    reason?: string
    data: QuestionResultsAggregationResult
}

Napomene o performansama

Kod promašaja keša (cache miss) agregacije obično traju oko pet sekundi po milionu rezultata.
U suprotnom, zahtevi su konstantnog vremena.

Napomene o keširanju i troškovima

Kada je navedeno forceRecalculate, trošak je uvek 10, umesto uobičajenih 2.
Ako keš istekne i podaci se ponovo izračunaju, trošak je i dalje konstantan 2 ako forceRecalculate nije naveden. Keš ističe na osnovu veličine agregiranog skupa podataka (može varirati između 30 sekundi i 5 minuta).
Ovo služi kao podsticaj za korišćenje keša.

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

Here are the query parameters available for aggregation:

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
}

Here's an example request:

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'

Example response:

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 дефиниције значке из каталога значки tenant-а */
    badgeId: string
    /** ID tenant-а који је креирао/доделио ову значку */
    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
}

---

GET /api/v1/user-badges

Овај крајњи пункт вам омогућава да преузмете значке корисника на основу различитих критеријума.

Пример захтева:

Пример 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, итд. Видите UserBadge структуру за пуну листу)
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

Ова крајња тачка вам омогућава да преузмете одређену корисничку значку по њеном јединственом ID-у.

Example Request:

Пример GET захтева

Copy

Run

curl -X GET "https://fastcomments.com/api/v1/user-badges/badge123?tenantId=demo&API_KEY=DEMO_API_SECRET"

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

Грешка: Није пронађено

Copy

{
  "status": "failed",
  "code": "not-found",
  "reason": "The user badge badge123 was not found."
}

---

POST /api/v1/user-badges

Ова крајња тачка вам омогућава да креирате ново додељивање ознаке кориснику.

Пример захтева:

Пример 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
}'

Тело захтева мора да садржи следеће параметре:

userId (обавезно) - ИД корисника коме се додељује ознака
badgeId (обавезно) - ИД ознаке која се додељује
displayedOnComments (опционо) - Да ли треба да се ознака приказује на коментарима корисника (подразумевано: true)

Важне напомене:

Ознака мора постојати и бити омогућена у каталогу ознака вашег тенанта
Ознаке можете доделити само корисницима који припадају вашем тенанту или су коментарисали на вашем сајту

Пример одговора:

Одговор

Copy

{
  "status": "success",
  "userBadge": {
    "id": "badge123",
    "userId": "user456",
    "badgeId": "badgeDef789",
    "fromTenantId": "tenant001",
    "createdAt": 1650532511000,
    "receivedAt": 1650532511000,
    "type": 14,
    "name": "Special Contributor",
    "description": "Awarded to special contributors to our community",
    "displayLabel": "Special",
    "backgroundColor": "#4a5568",
    "textColor": "#ffffff",
    "displayedOnComments": true,
    "order": 1
  }
}

Могући одговори са грешком:

Грешка: Недостаје ID тенанта

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Грешка: Недостаје ID корисника

Copy

{
  "status": "failed",
  "code": "missing-user-id",
  "reason": "User ID (body param: userId) is required."
}

Грешка: Недостаје 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

Овај endpoint вам омогућава да ажурирате додељивање корисничке ознаке.

Тренутно, једино својство које се може ажурирати је displayedOnComments, које контролише да ли се ознака приказује на коментарима корисника.

Example Request:

Пример PUT захтева

Copy

Run

curl -X PUT "https://fastcomments.com/api/v1/user-badges/badge123?tenantId=demo&API_KEY=DEMO_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
  "displayedOnComments": false
}'

Example Response:

Одговор

Copy

{
  "status": "success"
}

Possible Error Responses:

Грешка: Недостаје Tenant ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Грешка: Недостаје ID

Copy

{
  "status": "failed",
  "code": "missing-id",
  "reason": "The User Badge ID (url param: id) is missing."
}

Грешка: Није пронађено

Copy

{
  "status": "failed",
  "code": "not-found",
  "reason": "The user badge badge123 was not found."
}

DELETE /api/v1/user-badges/:id

Овај ендпоинт вам омогућава да избришете доделу значке кориснику.

Пример захтева:

Пример DELETE захтева

Copy

Run

curl -X DELETE "https://fastcomments.com/api/v1/user-badges/badge123?tenantId=demo&API_KEY=DEMO_API_SECRET"

Пример одговора:

Одговор

Copy

{
  "status": "success"
}

Могући одговори са грешком:

Грешка: Недостаје Tenant ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Грешка: Недостаје ID

Copy

{
  "status": "failed",
  "code": "missing-id",
  "reason": "The User Badge ID (url param: id) is missing."
}

Грешка: Није пронађено

Copy

{
  "status": "failed",
  "code": "not-found",
  "reason": "The user badge badge123 was not found."
}

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

UserBadgeProgress је објекат који представља напредак корисника ка стицању различитих значки у систему FastComments.

Ово праћење помаже у одређивању када корисници треба да добију аутоматске значке на основу своје активности и учешћа у вашој заједници.

Структура UserBadgeProgress објекта је следећа:

Структура UserBadgeProgress

Copy

export interface UserBadgeProgress {
    /** Јединствени идентификатор за овај запис напретка */
    id: string
    /** ID тенанта коме припада овај запис напретка */
    tenantId: string
    /** ID корисника кога овај запис напретка прати */
    userId: string
    /** ID првог коментара корисника у систему */
    firstCommentId?: string
    /** Датум првог коментара корисника (милисекунде од епохе) */
    firstCommentDate?: number
    /** Аутоматски израчунати фактор поверења на основу активности корисника */
    autoTrustFactor?: number
    /** Фактор поверења подешен ручно од стране администратора */
    manualTrustFactor?: number
    /** Детаљан објекат напретка са различитим метрикама, кључеви одговарају BadgeType енуму */
    progress: {
        /** 0: CommentCount - Број коментара које је корисник написао */
        '0'?: number
        /** 1: CommentUpVotes - Број позитивних гласова (upvotes) које је корисник примио */
        '1'?: number
        /** 2: CommentReplies - Број одговора које је корисник дао */
        '2'?: number
        /** 3: CommentsPinned - Број причвршћених (pinned) коментара које корисник има */
        '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

Ovaj endpoint vam omogućava da dohvatite zapise o napretku korisničkih znački na osnovu različitih kriterijuma.

Primer zahteva:

Primer GET zahteva

Copy

Run

curl -X GET "https://fastcomments.com/api/v1/user-badge-progress?tenantId=demo&API_KEY=DEMO_API_SECRET"

Možete dodati razne parametre upita da filtrirate rezultate:

userId - Dohvata napredak za konkretnog korisnika
limit - Maksimalan broj zapisa za vraćanje (podrazumevano 30, maksimum 200)
skip - Broj zapisa za preskakanje (za paginaciju)

Primer odgovora:

Odgovor

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

Mogući odgovori sa greškom:

Greška: Nedostaje ID tenanta

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Greška: Nevažeći limit

Copy

{
  "status": "failed",
  "code": "invalid-limit",
  "reason": "The limit (query param: limit) is too large (> 200)."
}

GET /api/v1/user-badge-progress/:id

Овај endpoint вам омогућава да дохватите одређени запис о напредовању корисничке значке по његовом јединственом 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

Ovaj endpoint вам омогућава да дохватите запис о напретку корисничке значке помоћу њиховог User ID.

Example Request:

Primer GET zahteva

Copy

Run

curl -X GET "https://fastcomments.com/api/v1/user-badge-progress/user/user456?tenantId=demo&API_KEY=DEMO_API_SECRET"

Example Response:

Odgovor

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

Possible Error Responses:

Greška: Nedostaje Tenant ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Greška: Nedostaje User ID

Copy

{
  "status": "failed",
  "code": "missing-user-id",
  "reason": "The User ID (path param: userId) is missing."
}

Greška: Nije pronađeno

Copy

{
  "status": "failed",
  "code": "not-found",
  "reason": "No badge progress found for user user456 in tenant tenant001."
}

У закључку

Надамо се да сматрате да је наша API документација детаљна и лака за разумевање. Ако уочите било какве пропусте, обавестите нас у наставку.

Језик 🇷🇸 Српски

API ресурси

Агрегације

Дневници ревизије

Коментари

Шаблони имејлова

Хештегови

Модератори

Број обавештења

Обавештења

Странице

Чекајући webhook догађаји

SSO корисници

Претплате

Дневна употреба тенанта

Тенанти

Пакети тенанта

Корисници тенанта

Корисници

Гласови

Конфигурације домена

Конфигурације питања

Резултати питања

Агрегација резултата питања

Ознаке корисника

Напредак ознака корисника

API платформе FastComments

Generated SDKs

Аутентификација

Напомена о безбедности

Authentication Option One - Headers

Authentication Option Two - Query Parameters

API ресурси

Korišćenje resursa

Napomena!

Агрегирајте своје податке

Primeri

Primer: Brojanje jedinstvenih

Primer: Prebrojavanje različitih vrednosti

Primer: Sabiranje vrednosti više polja

Primer: Prosečne vrednosti više polja

Primer: Minimalne/Maksimalne vrednosti više polja

Primer: Brojanje jedinstvenih vrednosti više polja

Primer: Kreiranje upita

Primer: Brojanje komentara na čekanju za pregled

Primer: Raspodela odobrenih, pregledanih i spam komentara

Strukture

Структура дневника ревизије

GET /api/v1/audit-logs

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

Struktura teksta komentara

Obeležavanje

Haštagovi

GET /api/v1/comments

Пагинација

Теме

Објашњење стабала

Преузимање коментара у контексту корисника

Добијање коментара као стабло

Добијање коментара као стабло, претраживање по хештегу

Сви параметри захтева

Одговор

Корисни савети

URL ID

Анонимне радње

Коментари се не враћају

GET /api/v1/comments/:id

POST /api/v1/comments

PATCH /api/v1/comments/:id

DELETE /api/v1/comments/:id

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

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

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

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

Структура шаблона имејла

Напомене

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

GET /api/v1/email-templates

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

POST /api/v1/email-templates