API | FastComments Docs

ממשק ה-API של FastComments

FastComments מספקת ממשק API לאינטראקציה עם משאבים רבים. צרו אינטגרציות עם הפלטפורמה שלנו, או אפילו צרו לקוחות משלכם!

בתיעוד זה תמצאו את כל המשאבים הנתמכים על ידי ה-API שתועדו עם סוגי הבקשה והתשובה שלהם.

ללקוחות Enterprise, כל הגישה ל-API נרשמת ביומן ביקורת.

SDKs שנוצרו

FastComments מייצרת כעת מפרט API מתוך הקוד שלנו (זה עדיין לא שלם, אך כולל ממשקי API רבים).

יש לנו גם SDKs לשפות נפוצות:

אימות

ה-API מאומת על ידי העברת מפתח ה-API שלך ככותרת X-API-KEY או כפרמטר שאילתה API_KEY. תזדקקו גם ל-tenantId כדי לבצע קריאות ל-API. ניתן לקבל אותו מאותה עמוד שבו נמצא מפתח ה-API שלכם.

הערת אבטחה

ניתובים אלה מיועדים להיקרא משרת. אסור לקרוא להם מדפדפן. פעולה כזו תחשוף את מפתח ה-API שלכם — וזה ייתן גישה מלאה לחשבון שלכם לכל מי שיכול לצפות בקוד המקור של דף!

אפשרות אימות אחת - כותרות

כותרת: X-API-KEY
כותרת: X-TENANT-ID

אפשרות אימות שנייה - פרמטרי שאילתה

פרמטר שאילתה: API_KEY
פרמטר שאילתה: tenantId

קריאה של הכתיבות שלך

FastComments מספקת זמינות Active-Active. בקשות ממרכז הנתונים שלכם מנותבות אל נקודת הנוכחות הקרובה אליכם. זה אוטומטי, ובדרך כלל תוכלו להבחין בסמנטיקה של קריאה אחרי כתיבה. אם ברצונכם להיות בטוחים שנקרא את הכתיבות שלכם, תוכלו לקבע את הבקשות לאזור מסוים על ידי שימוש באזור זה כ-host של ה-API (עם זאת, בדרך כלל זה לא נדרש עבור רוב האינטגרציות):

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

שימו לב שאם תעשו זאת ייתכן שתרצו להגדיר נקודת גיבוי, שכן בעבר הסרנו צמתים של נקודות כניסה והשתמשנו בשמות חדשים בעת המעבר.

משאבי API

שימוש במשאבים

יש לציין כי אחזור נתונים מה-API נספר כשימוש בחשבון שלך.

כל משאב יציין מה השימוש הזה בסעיף שלו.

חלק מהמשאבים יקרים יותר לשרת מאחרים. לכל נקודת קצה יש עלות קבועה של קרדיטים לכל קריאת API. עבור חלק מנקודות הקצה, מספר הקרדיטים משתנה בהתאם לאפשרויות ולגדלי התגובות.

ניתן לבדוק את השימוש ב-API בדף ניתוח חיוב והוא מתעדכן כל מספר דקות.

הערה!

אנו מציעים לקרוא קודם את תיעוד הדפים, כדי לסייע בהגבלת הבלבול בעת קביעת אילו ערכים להעביר עבור urlId ב-API של Comment.

לאגד את הנתונים שלך

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

API זה מצבר מסמכים על ידי קיבוצם (אם groupBy מסופק) והחלת פעולות מרובות. פעולות שונות (למשל sum, countDistinct, avg וכו') נתמכות.

העלות היא משתנה. כל 500 אובייקטים שנסרקים עולים 1 קרדיט API.

שימוש הזיכרון המקסימלי המותר לקריאת API היא 64MB כברירת מחדל, וכברירת מחדל מותר לך להריץ רק צבירה אחת בכל פעם. אם תשלח מספר צבירות בו-זמנית, הן יתווספו לתור ויורצו בסדר שהוגשו. צבירות ממתינות יחכו מקסימום 60 שניות, לאחר מכן הבקשה תפוג. צבירות בודדות יכולות לרוץ עד 5 דקות.

אם יש לך שוכרים מנוהלים, אתה יכול לצבור את כל משאבי שוכרי הילדים בקריאה אחת על ידי העברת פרמטר השאילתה parentTenantId.

דוגמאות

דוגמה: ספירת ייחודיים

דוגמת cURL לספירת ערכים ייחודיים

Copy

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

תגובת ספירת ערכים ייחודיים

Copy

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

דוגמה: ספירת נבדלים

דוגמת cURL לספירת ערכים נבדלים

Copy

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

תגובה:

תגובת ספירת ערכים נבדלים

Copy

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

דוגמה: סיכום ערכים של שדות מרובים

דוגמת cURL לסיכום ערכים

Copy

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

תגובה:

תגובת סיכום ערכים

Copy

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

דוגמה: ממוצע ערכים של שדות מרובים

דוגמת cURL לממוצע ערכים

Copy

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

תגובה:

תגובת ממוצע ערכים

Copy

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

דוגמה: ערכי מינימום/מקסימום של שדות מרובים

דוגמת cURL לערכי מינימום/מקסימום

Copy

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

תגובה:

תגובת ערכי מינימום/מקסימום

Copy

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

דוגמה: ספירת ערכים ייחודיים של שדות מרובים

דוגמת cURL לספירת ערכים ייחודיים

Copy

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

תגובה:

תגובת ספירת ערכים ייחודיים

Copy

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

דוגמה: יצירת שאילתה

דוגמת cURL ליצירת שאילתה

Copy

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

תגובה:

תגובת יצירת שאילתה

Copy

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

דוגמה: ספירת תגובות הממתינות לבדיקה

דוגמת cURL לספירת תגובות הממתינות לבדיקה

Copy

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

תגובה:

תגובת ספירת תגובות הממתינות לבדיקה

Copy

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

דוגמה: פירוט תגובות מאושרות, נבדקות וספאם

דוגמת cURL לפירוט תגובות

Copy

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

תגובה:

תגובת פירוט תגובות

Copy

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

מבנים

מבנה בקשת צבירה

Copy

export type AggregationOpType = 'sum' | 'countDistinct' | 'distinct' | 'avg' | 'min' | 'max' | 'count';
/** An operation that will be applied on a field */
export interface AggregationOperation {
    /** The field to operate on */
    field: string;
    /** The type of operation */
    op: AggregationOpType;
    /** Optional alias for the output; if not provided, a default alias is computed */
    alias?: string;
    expandArray?: boolean;
}
export interface QueryPredicate {
    key: string
    value: string | number | boolean
    operator: 'eq' | 'not_eq' | 'greater_than' | 'less_than' | 'contains'
}
export interface AggregationRequest {
    query?: QueryPredicate[];
    resourceName: string;
    groupBy?: string[];
    operations: AggregationOperation[];
    sort?: {
        field: string;
        dir: 'asc' | 'desc';
    };
}
type DistinctAccumulator = Record<string, number>;
type GroupValues = Record<string, string>;
export type AggregationValue = {
    distinctCounts?: DistinctAccumulator
    distinctCount?: number
    numericValue?: number
    stringValue?: string
    groups?: GroupValues
};

מבנה תגובת צבירה

Copy

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

המשאבים הבאים ניתנים לצבירה:

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

מבנה יומן ביקורת

אובייקט AuditLog מייצג אירוע מבוקר עבור שוכרים שיש להם גישה לתכונה זו.

המבנה עבור אובייקט AuditLog הוא כדלקמן:

מבנה AuditLog

Copy

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

יומן הביקורת הוא בלתי ניתן לשינוי. גם לא ניתן לכתוב אליו ידנית. FastComments.com עשוי להחליט מתי לכתוב ליומן הביקורת. עם זאת, אתה יכול לקרוא ממנו דרך API זה.

אירועים ביומן הביקורת פגים לאחר שנתיים.

GET /api/v1/audit-logs

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

API זה משתמש בעימוד, המסופק על ידי הפרמטרים skip, before ו-after. AuditLogs מוחזרים בדפים של 1000, ממוינים לפי when ו-id.

אחזור של כל 1000 יומנים עולה 10 קרדיטים.

כברירת מחדל, תקבל רשימה עם הפריטים החדשים ביותר ראשונים. בדרך זו, אתה יכול לתשאל החל מ-skip=0, לדפדף עד שתמצא את הרשומה האחרונה שצרכת.

לחלופין, אתה יכול למיין מהישן לחדש, ולדפדף עד שאין יותר רשומות.

ניתן לבצע מיון על ידי הגדרת order ל-ASC או DESC. ברירת המחדל היא ASC.

שאילתה לפי תאריך אפשרית דרך before ו-after כחותמות זמן עם מילישניות. before ו-after אינם כוללניים.

דוגמת cURL ל-AuditLog

Copy

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

מבנה בקשת AuditLog

Copy

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

מבנה תגובת AuditLog

Copy

interface CommentsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    /** The logs! **/
    auditLogs: AuditLog[]
}

מבנה תגובה

אובייקט Comment מייצג תגובה שהשאיר משתמש.

הקשר בין תגובות אב וצאצא מוגדר באמצעות parentId.

המבנה של אובייקט Comment הוא כדלקמן:

מבנה תגובה

Copy

interface Comment {
    /** לקריאה בלבד: יוגדר ל-true אם מנוע הספאם קבע שהתגובה היא ספאם. **/
    aiDeterminedSpam?: boolean
    /** האם התגובה מאושרת להצגה. תוגדר ל-true בעת שמירת התגובה; אחרת היא תוסתר. **/
    approved?: boolean
    /** האווטאר של המשתמש. **/
    avatarSrc?: string
    /** Child comments. Not populated in all scenarios. Used when asTree is set to true via the API. **/
    children: Comment[]
    /** הטקסט הגולמי של התגובה. **/
    comment: string
    /** לקריאה בלבד: הטקסט של התגובה לאחר פירוס ל-HTML. **/
    commentHTML?: string
    /** האימייל של הכותב. נדרש אם תגובות אנונימיות כבויות. **/
    commenterEmail?: string
    /** הקישור של הכותב (למשל הבלוג שלו). **/
    commenterLink?: string
    /** השם של הכותב. תמיד נדרש. אם לא זמין, קבע ערך כמו "Anonymous". **/
    commenterName: string
    /** התאריך שבו נכתבה התגובה, ביחידת זמן epoch UTC. **/
    date: number
    /** התווית לתצוגה של התגובה - לדוגמה "Admin", "Moderator", או משהו כמו "VIP User". **/
    displayLabel?: string
    /** הדומיין שבו פורסמה התגובה. **/
    domain?: string
    /** לקריאה בלבד: מספר הפעמים שהתגובה סומנה. **/
    flagCount?: number
    /** ההאשטאגים (#) שנכתבו בתגובה ופוענחו בהצלחה. ניתן גם להוסיף האשטאגים ידנית לצורך שאילתות, אך הם לא יוצגו אוטומטית בטקסט התגובה. **/
    hashTags?: CommentHashTag[]
    /** לקריאה בלבד: האם התגובה מכילה תמונות? **/
    hasImages?: boolean
    /** לקריאה בלבד: האם התגובה מכילה קישורים? **/
    hasLinks?: boolean
    /** לקריאה בלבד: המזהה הייחודי של התגובה. **/
    id: string
    /** רק בעת יצירה! ערך זה מעובד ב-hash לצורך אחסון. **/
    ip?: string
    /** לקריאה בלבד: האם המשתמש הנוכחי חסם את מי שכתב את התגובה? **/
    isBlocked?: boolean
    /** לקריאה בלבד: האם התגובה נכתבה על ידי אדמין? מוגדר אוטומטית על בסיס userId. **/
    isByAdmin?: boolean
    /** לקריאה בלבד: האם התגובה נכתבה על ידי מודראטור? מוגדר אוטומטית על בסיס userId. **/
    isByModerator?: boolean
    /** יוגדר ל-true אם התגובה נמחקה באופן רך (soft deleted) — הושאר ממלא מקום בשל קונפיגורציה אחרת. **/
    isDeleted?: boolean
    /** יוגדר ל-true אם חשבון המשתמש נמחק והתגובה נדרשה להישאר. **/
    isDeletedUser?: boolean
    /** לקריאה בלבד: האם התגובה סומנה על ידי המשתמש המחובר כרגע (contextUserId)? **/
    isFlagged?: boolean
    /** האם התגובה מוצמדת (pinned)? **/
    isPinned?: boolean
    /** האם התגובה נעולה? כאשר true, אף אחד (כולל מודראטורים) לא יכול להשיב, לערוך או למחוק אותה עד שתיפתח. **/
    isLocked?: boolean
    /** האם התגובה היא ספאם? **/
    isSpam?: boolean
    /** לקריאה בלבד: האם המשתמש הנוכחי (contextUserId) הצביע נגד התגובה? **/
    isVotedDown?: boolean
    /** לקריאה בלבד: האם המשתמש הנוכחי (contextUserId) הצביע בעד התגובה? **/
    isVotedUp?: boolean
    /** השפה/לוקל של התגובה. אם לא סופק, היא נגזרת מכותרת ה-HTTP שמציינת את שפות ההעדפה. **/
    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'
    /** לקריאה בלבד: ה-@mentions שנכתבו בתגובה ופוענחו בהצלחה. **/
    mentions?: CommentUserMention[]
    /** מטה-נתונים אופציונליים המשויכים לתגובה. **/
    meta?: Record<string, string | number | boolean>
    /** The optional list of moderation group ids associated with this comment. **/
    moderationGroupIds?: string[]|null
    /** לקריאה בלבד: המזהה של אובייקט ההצבעה המתאים להצבעת המשתמש הנוכחי (contextUserId) על תגובה זו. **/
    myVoteId?: string
    /** האם נשלחו התראות על תגובה זו למגיבים. כדי למנוע שליחת התראות בייבוא, קבע ערך זה ל-true. **/
    notificationSentForParent?: boolean
    /** האם נשלחו התראות על תגובה זו למשתמשי ה-tenant. כדי למנוע שליחת התראות בייבוא, קבע ל-true. **/
    notificationSentForParentTenant?: boolean
    /** הכותרת של העמוד שבו הופיעה התגובה. **/
    pageTitle?: string
    /** אם אנו משיבים לתגובה, זהו המזהה שאליו משיבים. **/
    parentId?: string|null
    /** האם התגובה מסומנת כנגועה בבדיקה (reviewed). **/
    reviewed: boolean
    /** מזהה ה-tenant שאליו שייכת התגובה. **/
    tenantId: string
    /** המשתמש שכתב את התגובה. נוצר אוטומטית כאשר שומרים תגובה שכוללת שם/אימייל. **/
    userId?: string|null
    /** ה-URL למיקום שבו התגובה נראית, לדוגמה פוסט בבלוג. **/
    url: string
    /** גרסה "נוקה" של ה-urlId שסיפקת. בעת שמירה, אתה מציין שדה זה, אך כאשר משחזרים את התגובה הוא יעובד והערך המקורי יועבר ל-"urlIdRaw". **/
    urlId: string
    /** לקריאה בלבד: ה-urlId המקורי שסיפקת. **/
    urlIdRaw?: string
    /** האם המשתמש והתגובה מאומתים? **/
    verified: boolean
    /** מספר ההצבעות בעד. **/
    votesUp?: number
    /** מספר ההצבעות נגד. **/
    votesDown?: number
    /** "הקרמה" של התגובה (= votes up - votes down). **/
    votes?: number
}

חלק מהשדות הללו מסומנים כ-READONLY - אלה מוחזרים על ידי ה-API אך לא יכולים להיות מוגדרים.

Comment Text Structure

תגובות נכתבות בגירסה של Markdown שמותאמת ל-FastComments, שהיא Markdown בתוספת תגים בסגנון bbcode עבור תמונות, כמו [img]path[/img].

הטקסט נשמר בשני שדות. הטקסט שהמשתמש הזין נשמר ללא שינוי בשדה comment. זה מורנדר ונשמר בשדה commentHTML.

תגי ה-HTML המותרים הם b, u, i, strike, pre, span, code, img, a, strong, ul, ol, li, and br.

מומלץ להציג את ה-HTML, מכיוון שמדובר בתת-קבוצה מאוד קטנה של HTML, ובניית מנרדרר היא יחסית פשוטה. קיימות ספריות רבות עבור React Native ו-Flutter, למשל, שעוזרות בכך.

אתה רשאי לבחור להציג את הערך הלא-נורמליזציוני של השדה comment. An example parser is here..

ניתן גם להתאים את מפענח הדוגמה לעבודה עם HTML, ולהמיר את תווי ה-HTML לאלמנטים הצפויים להצגה בפלטפורמה שלך.

Tagging

כאשר משתמשים מסומנים בתגובה, המידע מאוחסן ברשימה שנקראת mentions. כל אובייקט ברשימה זו יש את המבנה הבא.

אובייקט אזכורי התגובה

Copy

Run

interface CommentUserMention {
    /** מזהה המשתמש. עבור משתמשי SSO, יהיה עם קידומת של מזהה ה-tenant שלכם. **/
    id: string
    /** הטקסט הסופי של תגית ה-@mention, כולל הסימן @. **/
    tag: string
    /** הטקסט המקורי של ה-@mention, כולל הסימן @. **/
    rawTag: string
    /** סוג המשתמש שהוזכר. user = FastComments.com account. sso = SSOUser. **/
    type: 'user'|'sso'
    /** גם אם המשתמש מבטל קבלת התראות, ערך זה עדיין יהיה true. **/
    sent: boolean
}

HashTags

כאשר משתמשים בהאשטאגים והם פוענחו בהצלחה, המידע מאוחסן ברשימה שנקראת hashTags. כל אובייקט ברשימה זו יש את המבנה הבא. ניתן גם להוסיף האשטאגים ידנית למערך hashTags של התגובה לצורך שאילתות, אם retain מוגדר.

אובייקט האשטאג של התגובה

Copy

Run

interface CommentHashTag {
    /** המזהה של ההאשטאג. **/
    id: string
    /** הטקסט הסופי של תגית ה-#hashtag, כולל הסימן #. **/
    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. לחיצה על "הבא" פשוט מגדילה את מספר העמוד.
3. אתה יכול לחשוב על זה כאילו הנתונים מאוחזרים ממאגר מפתח-ערך.
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.

שרשורים

בעת שימוש ב-עימוד מחושב מראש, תגובות מקובצות לפי עמוד ותגובות בשרשורים משפיעות על העמוד הכולל.
1. בדרך זו, ניתן לקבוע שרשורים בצד הלקוח בהתבסס על parentId.
2. לדוגמה, עם עמוד עם תגובה אחת ברמה העליונה, ו-29 תשובות, והגדרת page=0 ב-API - תקבל רק את התגובה ברמה העליונה ו-29 הילדים.
3. תמונת דוגמה כאן הממחישה מספר עמודים.
בעת שימוש ב-עימוד גמיש, אתה יכול להגדיר פרמטר parentId.
1. הגדר אותו ל-null כדי לקבל רק תגובות ברמה העליונה.
2. לאחר מכן כדי לצפות בשרשורים, קרא שוב ל-API והעבר parentId.
3. פתרון נפוץ הוא לבצע קריאת API לתגובות ברמה העליונה ולאחר מכן לבצע קריאות API במקביל לקבלת תגובות לילדים של כל תגובה.
חדש מפברואר 2023! אחזר כעץ באמצעות &asTree=true.
1. אתה יכול לחשוב על זה כ-עימוד גמיש כעץ.
2. רק התגובות ברמה העליונה נספרות בעימוד.
3. הגדר parentId=null כדי להתחיל את העץ בשורש (אתה חייב להגדיר parentId).
4. הגדר skip ו-limit לעימוד.
5. הגדר asTree ל-true.
6. עלות הקרדיטים עולה פי 2x, מכיוון שהשרת שלנו צריך לעשות הרבה יותר עבודה בתרחיש זה.
7. הגדר maxTreeDepth, limitChildren, ו-skipChildren כרצונך.

הסבר עצים

בעת שימוש ב-asTree, יכול להיות קשה להבין את העימוד. הנה גרפיקה שימושית:

תרשים עימוד עץ

אחזור תגובות בהקשר של משתמש

ניתן להשתמש ב-API /comments בשני הקשרים, למקרי שימוש שונים:

להחזרת תגובות ממוינות ומתויגות עם מידע לבניית הלקוח שלך.
- במקרה זה, הגדר פרמטר שאילתה contextUserId.
לאחזור תגובות מהשרת שלך לאינטגרציות מותאמות אישית.
- הפלטפורמה תעבור לברירת מחדל זו ללא contextUserId.

עימוד מחושב מראש לתגובות

Copy

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

עימוד גמיש לתגובות

Copy

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

עימוד גמיש לתגובות בהקשר משתמש

Copy

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

עימוד גמיש לתגובות בהקשר משתמש לתגובות ברמה העליונה בלבד

Copy

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

קבלת תגובות כעץ

ניתן לקבל את התגובות מוחזרות כעץ, כאשר העימוד סופר רק את התגובות ברמה העליונה.

תגובות כעץ בהקשר משתמש

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null&asTree=true'

רוצה לקבל רק את התגובות ברמה העליונה והילדים המיידיים? הנה דרך אחת:

תגובות כעץ עם עומק מקסימלי

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null&asTree=true&maxTreeDepth=1&limitChildren=10'

עם זאת, בממשק המשתמש שלך ייתכן שתצטרך לדעת האם להציג כפתור "הצג תשובות" על כל תגובה. בעת אחזור תגובות באמצעות עץ יש מאפיין hasChildren המתויג על תגובות כאשר רלוונטי.

קבלת תגובות כעץ, חיפוש לפי האשטאג

ניתן לחפש לפי האשטאג באמצעות ה-API, בכל השוכר שלך (לא מוגבל לעמוד אחד, או urlId).

בדוגמה זו, אנחנו משמיטים urlId, ומחפשים לפי מספר האשטאגים. ה-API יחזיר רק תגובות שיש להן את כל ההאשטאגים המבוקשים.

תגובות כעץ בהקשר משתמש, לפי האשטאג

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null&asTree=true&hashTag=TestTag&hashTag=OtherTestTag'

כל פרמטרי הבקשה

מבנה בקשת תגובות

Copy

interface CommentsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** 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

סביר להניח שתרצה להשתמש ב-API של Comment עם פרמטר urlId. אתה יכול לקרוא קודם ל-API של Pages, כדי לראות איך נראים ערכי urlId הזמינים לך.

פעולות אנונימיות

לתגובות אנונימיות סביר להניח שתרצה להעביר anonUserId בעת אחזור תגובות, ובעת ביצוע דיווח וחסימה.

(!) זה נדרש עבור חנויות אפליקציות רבות מכיוון שמשתמשים חייבים להיות מסוגלים לדווח על תוכן שנוצר על ידי משתמשים שהם יכולים לראות, גם אם הם לא מחוברים. אי עשיית זאת עלולה לגרום להסרת האפליקציה שלך מהחנות האמורה.

תגובות לא מוחזרות

בדוק שהתגובות שלך מאושרות, ואינן ספאם.

GET /api/v1/comments/:id

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

API זה מספק את היכולת לאחזר תגובה בודדת לפי מזהה.

דוגמת cURL לאחזור תגובה לפי מזהה

Copy

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

מבנה בקשת אחזור תגובה לפי מזהה

Copy

interface CommentsGetByIdQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת אחזור תגובה לפי מזהה

Copy

interface CommentGetByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'missing-id'
    /** Included on failure. **/
    reason?: string
    /** The comment! **/
    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'
    /** Whether the comment should appear "live" to users viewing instances of the comment widget with the same urlId. NOTE: Doubles credit cost from 1 to 2. **/
    isLive?: 'true' | 'false'
    sendEmails?: 'true' | 'false'
    populateNotifications?: 'true' | 'false'
}

מבנה תגובת POST תגובה

Copy

interface CommentPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    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';
    /** Included on failure. **/
    reason?: string
    /** The created comment. **/
    comment?: Comment
    /** The associated user, which may or may not have already existed. **/
    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 באופן אוטומטי.
- אם המשתמש יוסיף אזכורים או האשטגים בטקסט החדש שלו, הם עדיין יעובדו כמו ב-API ה-POST.
בעת עדכון commenterEmail על תגובה, עדיף גם לציין userId. אחרת, עליך להבטיח שהמשתמש עם אימייל זה שייך ל-tenant שלך, אחרת הבקשה תיכשל.
אם התגובה היעד נעולה (isLocked: true), הבקשה תידחה עם code: 'locked'. פתח את התגובה קודם, עדכן אותה, ואז נעל שוב אם רצוי.

דוגמת cURL מינימלית ל-PATCH של תגובה

Copy

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

מבנה בקשת PATCH לתגובה

Copy

interface CommentPatchQueryParams {
    tenantId: string
    API_KEY: string
    /** המשתמש שעושה את העדכון. במידת הצורך ניתן להשתמש בזה כדי לבדוק שהוא יכול לערוך את התגובה.  **/
    contextUserId?: string
    /** האם יש לבדוק אם התגובה החדשה נראית כספאם?  **/
    doSpamCheck?: 'true' | 'false'
    /** האם התגובה תופיע "בזמן אמת" למשתמשים הצופים במופעים של ווידג'ט התגובות עם אותו urlId. הערה: מכפיל את עלות הקרדיטים מ-1 ל-2. **/
    isLive?: 'true' | 'false'
}

מבנה תשובת PATCH לתגובה

Copy

interface CommentPatchResponse {
    status: 'success' | 'failed'
    /** נכלל במקרה של כישלון. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-comment' | 'comment-too-big' | 'hash-tags-readonly' | 'mentions-readonly' | 'invalid-user' | 'unauthorized' | 'invalid-date' | 'invalid-name' | 'invalid-name-is-email' | 'banned' | 'invalid-email' | 'invalid-input' | 'missing-id' | 'not-found' | 'locked'
    /** נכלל במקרה של כישלון. **/
    reason?: string
}

DELETE /api/v1/comments/:id

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

נקודת קצה זו של ה-API מאפשרת למחוק תגובה.

הערות:

API זה יכול לעדכן את ווידג'ט התגובות "בלייב" אם רצוי (זה מעלה את creditsCost מ-1 ל-2).
ה-API ימחק את כל תגובות המשנה.
אם התגובה המיועדת נעולה (isLocked: true), הבקשה תידחה עם code: 'locked'. הסר את הנעילה של התגובה תחילה, ואז מחק אותה.

דוגמת cURL למחיקת תגובה

Copy

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

מבנה בקשת DELETE לתגובה

Copy

interface CommentDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** המשתמש שמבצע את העדכון. במידת הצורך ניתן להשתמש בו כדי לבדוק שהוא יכול למחוק את התגובה.  **/
    contextUserId?: string
    /** האם יש למחוק את התגובה "בלייב" עבור משתמשים הצופים במופעים של ווידג'ט התגובות עם אותו urlId. שימו לב: מכפיל את עלות האשראי מ-1 ל-2. **/
    isLive?: 'true' | 'false'
}

מבנה תגובת מחיקת תגובה

Copy

interface CommentDeleteResponse {
    status: 'success' | 'failed'
    /** כלול במקרה של כישלון. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'locked'
    /** כלול במקרה של כישלון. **/
    reason?: string
}

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

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

נקודת קצה API זו מספקת את היכולת לדווח על תגובה עבור משתמש ספציפי.

הערות:

קריאה זו חייבת תמיד להיעשות בהקשר של משתמש. המשתמש יכול להיות משתמש FastComments.com, משתמש SSO או משתמש שוכר.
אם מוגדר סף דיווח-להסתרה, התגובה תוסתר אוטומטית בזמן אמת לאחר שדווחה את מספר הפעמים המוגדר.
לאחר שהיא מאושרת אוטומטית (מוסתרת) - התגובה יכולה להיות מאושרת מחדש רק על ידי מנהל או מנחה. ביטול הדיווח לא יאשר מחדש את התגובה.

דוגמת cURL לדיווח על תגובה

Copy

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

לדיווח אנונימי, עלינו לציין anonUserId. זה יכול להיות מזהה שמייצג את ההפעלה האנונימית, או UUID אקראי. זה מאפשר לנו לתמוך בדיווח וביטול דיווח על תגובות גם אם משתמש לא מחובר. בדרך זו, התגובה יכולה להיות מסומנת כמדווחת כאשר תגובות נאחזות עם אותו 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'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id'
    /** Included on failure. **/
    reason?: string
    /** Was the comment un-approved (hidden) due to being flagged too many times? **/
    wasUnapproved?: boolean;
}

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

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

נקודת קצה API זו מספקת את היכולת לבטל דיווח על תגובה עבור משתמש ספציפי.

הערות:

קריאה זו חייבת תמיד להיעשות בהקשר של משתמש. המשתמש יכול להיות משתמש FastComments.com, משתמש SSO או משתמש שוכר.
לאחר שתגובה מאושרת אוטומטית (מוסתרת) - התגובה יכולה להיות מאושרת מחדש רק על ידי מנהל או מנחה. ביטול הדיווח לא יאשר מחדש את התגובה.

דוגמת 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'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id'
    /** Included on failure. **/
    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 בבקשה הוא המשתמש שמבצע את החסימה. לדוגמה: משתמש א' רוצה לחסום את משתמש ב'. העבר userId=משתמש א' ואת מזהה התגובה שמשתמש ב' כתב.
תגובות אנונימיות לחלוטין (ללא מזהה משתמש, ללא אימייל) לא ניתנות לחסימה ושגיאה תוחזר.

דוגמת cURL לחסימת תגובה

Copy

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

לחסימה אנונימית, עלינו לציין anonUserId. זה יכול להיות מזהה שמייצג את ההפעלה האנונימית, או UUID אקראי. זה מאפשר לנו לתמוך בחסימת תגובות גם אם משתמש לא מחובר על ידי אחזור התגובות עם אותו anonUserId.

דוגמת cURL לחסימת תגובה אנונימית

Copy

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

מבנה בקשת חסימת תגובה

Copy

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

מבנה תגובת חסימת תגובה

Copy

interface CommentBlockResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    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'
    /** Included on failure. **/
    reason?: string
    /** If commentIdsToCheck is defined, entries in this map with true are also blocked. **/
    commentStatuses?: Record<string, boolean>;
}

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

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

נקודת קצה API זו מספקת את היכולת לבטל חסימה של משתמש שכתב תגובה נתונה. היא תומכת בביטול חסימה מתגובות שנכתבו על ידי משתמשי FastComments.com, משתמשי SSO ומשתמשי שוכר.

הערות:

קריאה זו חייבת תמיד להיעשות בהקשר של משתמש. המשתמש יכול להיות משתמש FastComments.com, משתמש SSO או משתמש שוכר.
ה-userId בבקשה הוא המשתמש שמבצע את ביטול החסימה. לדוגמה: משתמש א' רוצה לבטל חסימה של משתמש ב'. העבר userId=משתמש א' ואת מזהה התגובה שמשתמש ב' כתב.
תגובות אנונימיות לחלוטין (ללא מזהה משתמש, ללא אימייל) לא ניתנות לחסימה ושגיאה תוחזר.

דוגמת cURL לביטול חסימת תגובה

Copy

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

דוגמת cURL לביטול חסימת תגובה אנונימית

Copy

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

מבנה בקשת ביטול חסימת תגובה

Copy

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

מבנה תגובת ביטול חסימת תגובה

Copy

interface CommentUnBlockResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    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'
    /** Included on failure. **/
    reason?: string
    /** If commentIdsToCheck is defined, entries in this map with true are still blocked. If false, you might want to un-hide the comments from the user so they don't have to refresh. **/
    commentStatuses?: Record<string, boolean>;
}

מבנה תבנית דוא״ל

אובייקט EmailTemplate מייצג קונפיגורציה לתבנית אימייל מותאמת אישית, עבור שוכר.

המערכת תבחר את תבנית האימייל לשימוש באמצעות:

מזהה הסוג שלה, אנחנו קוראים לזה emailTemplateId. אלה קבועים.
ה-domain. אנחנו קודם ננסה למצוא תבנית עבור הדומיין שהאובייקט הקשור (כמו Comment) קשור אליו, ואם לא נמצאה התאמה אז ננסה למצוא תבנית שבה domain הוא null או *.

המבנה עבור אובייקט EmailTemplate הוא כדלקמן:

מבנה תבנית אימייל

Copy

interface EmailTemplate {
    id: string
    tenantId: string
    emailTemplateId: string
    displayName: string
    /** READONLY **/
    createdAt: string
    /** READONLY **/
    updatedAt: string
    /** READONLY **/
    updatedByUserId: string
    /** The domain the template should be associated with. **/
    domain?: string | '*' | null
    /** The email template content in EJS syntax. **/
    ejs: string
    /** A map of overridden translation keys to values, for each supported locale. **/
    translationOverridesByLocale: Record<string, Record<string, string>>
    /** An object that represents the render context of the template. **/
    testData: object
}

הערות

אתה יכול לקבל את ערכי emailTemplateId החוקיים מנקודת הקצה /definitions.
נקודת הקצה /definitions כוללת גם את התרגומים ברירת המחדל ונתוני הבדיקה.
תבניות ייכשלו בשמירה עם מבנה או נתוני בדיקה לא חוקיים.

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

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

ניתן לאחזר תבניות אימייל בודדות לפי ה-id התואם שלהן (לא emailTemplateId).

דוגמת cURL לתבנית אימייל לפי מזהה

Copy

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

מבנה בקשת תבנית אימייל לפי מזהה

Copy

interface EmailTemplatesByIdRequestQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת תבנית אימייל לפי מזהה

Copy

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

GET /api/v1/email-templates

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

API זה משתמש בעימוד, המסופק על ידי פרמטר השאילתה page. תבניות אימייל מוחזרות בעמודים של 100, ממוינות לפי createdAt ולאחר מכן id.

דוגמת cURL לתבנית אימייל

Copy

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

מבנה בקשת תבנית אימייל

Copy

interface EmailTemplatesRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The page to fetch, starting with 0. **/
    page: number
}

מבנה תגובת תבנית אימייל

Copy

interface EmailTemplatesResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    emailTemplates: EmailTemplate[]
}

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

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

נקודת קצה API זו מספקת את היכולת לעדכן תבנית אימייל על ידי ציון המזהה והמאפיינים לעדכון בלבד.

שים לב שכל אותן בדיקות אימות ליצירת תבנית חלות גם כן, לדוגמה:

התבנית חייבת להירנדר. זה נבדק עם כל עדכון.
לא יכולות להיות תבניות כפולות לאותו דומיין (אחרת אחת תתעלם בשקט).

דוגמת cURL ל-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",
}'

מבנה בקשת PATCH תבנית אימייל

Copy

interface EmailTemplatePatchQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת PATCH תבנית אימייל

Copy

interface EmailTemplatePatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'not-found' | 'unexpected-param' | 'invalid-email-template-id' | 'unauthorized' | 'domain-invalid' | 'duplicate' | 'does-not-render';
    /** Included on failure. **/
    reason?: string
    /** The updated email template. **/
    emailTemplate?: EmailTemplate
}

POST /api/v1/email-templates

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

נקודת קצה API זו מספקת את היכולת ליצור תבניות אימייל.

הערות:

לא יכולות להיות מספר תבניות עם אותו emailTemplateId עם אותו דומיין.
אבל אתה יכול לקבל תבנית עם תו כללי (domain = * ותבנית ספציפית לדומיין לאותו emailTemplateId).
ציון domain רלוונטי רק אם יש לך דומיינים שונים, או רוצה להשתמש בתבניות ספציפיות לבדיקות (domain מוגדר ל-localhost וכד').
אם אתה כן מציין domain הוא חייב להתאים ל-DomainConfig. בשגיאה מסופקת רשימה של דומיינים חוקיים.
תחביר התבנית הוא EJS והיא מרונדרת עם timeout של 500ms. P99 לרנדור הוא <5ms, אז אם אתה מגיע ל-500ms משהו לא בסדר.
התבנית שלך חייבת להירנדר עם ה-testData הנתון כדי להישמר. שגיאות רנדור נאספות ומדווחות בדשבורד (בקרוב יהיה זמין דרך API).

הנתונים המינימליים הנדרשים להוספת תבנית הם כדלקמן:

דוגמת cURL מינימלית ל-POST תבנית אימייל

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:

דוגמת cURL ל-POST תבנית אימייל

Copy

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

מבנה בקשת POST תבנית אימייל

Copy

interface EmailTemplatePostQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת POST תבנית אימייל

Copy

interface EmailTemplatePostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'unexpected-param' | 'invalid-email-template-id' | 'domain-invalid' | 'duplicate' | 'does-not-render';
    /** Included on failure. **/
    reason?: string
    /** The created template. **/
    emailTemplate?: EmailTemplate
}

POST /api/v1/email-templates/render

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

נקודת קצה API זו מספקת את היכולת להציג תצוגה מקדימה של תבניות אימייל.

דוגמת cURL מינימלית ל-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'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'unexpected-param' | 'does-not-render';
    /** Included on failure. **/
    reason?: string
    /** The rendered HTML on success. **/
    html?: string
}

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

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

נתיב זה מספק הסרה של EmailTemplate יחידה לפי מזהה.

דוגמת cURL להסרת תבנית אימייל

Copy

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

מבנה בקשת הסרת תבנית אימייל

Copy

interface EmailTemplateRequestQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת הסרת תבנית אימייל

Copy

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

מבנה תגית

אובייקט HashTag מייצג תגית שיכולה להיות מושארת על ידי משתמש. האשטאגים יכולים לשמש לקישור לתוכן חיצוני או לקשר תגובות קשורות יחד.

המבנה עבור אובייקט HashTag הוא כדלקמן:

מבנה האשטאג

Copy

interface HashTag {
    /** Should start with the "#" or desired character. **/
    tag: string
    /** An optional URL that the hashtag can point to. Instead of filtering comments by hashtag, the UI will redirect to this upon click. **/
    url?: string
    /** READONLY **/
    createdAt: string
}

הערות:

בחלק מנקודות הקצה של ה-API תראה שההאשטאג משמש ב-URL. זכור לקודד URI את הערכים. לדוגמה, # צריך להיות מיוצג כ-%23.
חלק מהשדות הללו מסומנים כ-READONLY - אלה מוחזרים על ידי ה-API אבל לא ניתן להגדיר אותם.

GET /api/v1/hash-tags

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

API זה משתמש בעימוד, המסופק על ידי פרמטר השאילתה page. האשטאגים מוחזרים בעמודים של 100, ממוינים לפי tag.

דוגמת cURL להאשטאג

Copy

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

מבנה בקשת האשטאג

Copy

interface HashTagsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The page to fetch, starting with 0. **/
    page: number
}

מבנה תגובת האשטאג

Copy

interface HashTagsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    /** The hashtags! **/
    hashTags: HashTag[]
}

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

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

נתיב זה מספק את היכולת לעדכן HashTag יחיד.

דוגמת cURL לעדכון האשטאג

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

מבנה בקשת עדכון האשטאג

Copy

interface HashTagPatchQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת עדכון האשטאג

Copy

interface HashTagPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    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'
    /** Included on failure. **/
    reason?: string
    hashTag?: HashTag; // We return the complete updated hashtag on success.
}

POST /api/v1/hash-tags

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

נתיב זה מספק את היכולת להוסיף HashTag יחיד.

דוגמת cURL ליצירת האשטאג

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

מבנה בקשת יצירת האשטאג

Copy

interface HashTagPostQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת יצירת האשטאג

Copy

interface HashTagPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    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'
    /** Included on failure. **/
    reason?: string
    hashTag?: HashTag; // We return the complete created hashtag on success.
}

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'
    /** Included on failure. **/
    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'
    /** Included on failure. **/
    reason?: string
    results?: HashTagPostResponse[]; // We return a list of HashTagPostResponse objects for each provided tag.
}

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

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

נתיב זה מספק את הסרת HashTag לפי התגית שסופקה.

שים לב שאלא אם יצירת HashTag אוטומטית מושבתת, האשטאגים יכולים להיווצר מחדש על ידי משתמש שמספק את ההאשטאג בעת תגובה.

דוגמת cURL להסרת האשטאג

Copy

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

מבנה בקשת הסרת האשטאג

Copy

interface HashTagDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת הסרת האשטאג

Copy

interface HashTagDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist'
    /** Included on failure. **/
    reason?: string
}

מבנה מודרטור

אובייקט Moderator מייצג קונפיגורציה עבור מנהל תוכן.

ישנם שלושה סוגים של מנהלי תוכן:

משתמשי מנהלים שיש להם את הדגל isCommentModeratorAdmin.
משתמשי SSO עם הדגל isCommentModeratorAdmin.
מגיבים רגילים, או משתמשי FastComments.com, שהוזמנו כמנהלי תוכן.

מבנה Moderator משמש לייצג את מצב ניהול התוכן של מקרה שימוש 3.

אם אתה רוצה להזמין משתמש להיות מנהל תוכן, דרך ה-API, השתמש ב-API של Moderator על ידי יצירת Moderator והזמנתם.

אם למשתמש אין חשבון FastComments.com, אימייל ההזמנה יעזור לו להתחיל. אם כבר יש לו חשבון, הוא יקבל גישת ניהול תוכן לשוכר שלך ומאפיין userId של אובייקט ה-Moderator יתעדכן להצביע על המשתמש שלו. לא תהיה לך גישת API למשתמש שלהם, כי במקרה זה הוא שייך להם ומנוהל על ידי FastComments.com.

אם אתה דורש ניהול מלא של חשבון המשתמש, אנחנו ממליצים להשתמש ב-SSO, או להוסיף אותם כ-משתמש שוכר ו לאחר מכן להוסיף אובייקט Moderator למעקב אחר הסטטיסטיקות שלהם.

ניתן להשתמש במבנה Moderator כמנגנון מעקב סטטיסטיקות עבור מקרי שימוש 1 ו-2. לאחר יצירת המשתמש, הוסף אובייקט Moderator עם userId שלו מוגדר והסטטיסטיקות שלו יעקבו ב-דף מנהלי התגובות.

המבנה עבור אובייקט 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

נתיב זה מחזיר מנהל תוכן יחיד לפי המזהה שלו.

דוגמת cURL למנהל תוכן לפי מזהה

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'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
    moderator?: Moderator
}

GET /api/v1/moderators

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

API זה משתמש בעימוד, המסופק על ידי פרמטר השאילתה skip. מנהלי תוכן מוחזרים בעמודים של 100, ממוינים לפי createdAt ו-id.

העלות מבוססת על מספר מנהלי התוכן המוחזרים, עולה 1 קרדיט לכל 10 מנהלי תוכן מוחזרים.

דוגמת cURL למנהל תוכן

Copy

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

מבנה בקשת מנהל תוכן

Copy

interface ModeratorsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The number of moderators to skip for pagination. **/
    skip?: number
}

מבנה תגובת מנהל תוכן

Copy

interface ModeratorsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    moderators?: Moderator[]
}

PATCH /api/v1/moderators/:id

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

נקודת קצה API זו מספקת את היכולת לעדכן Moderator לפי id.

לעדכון Moderator יש את ההגבלות הבאות:

אין לספק את הערכים הבאים בעת עדכון Moderator:
- acceptedInvite
- markReviewedCount
- deletedCount
- markedSpamCount
- approvedCount
- editedCount
- bannedCount
- verificationId
- createdAt
כאשר מצוין userId, המשתמש הזה חייב להתקיים.
כאשר מצוין userId, הוא חייב להשתייך לאותו tenantId שצוין בפרמטרי השאילתה.
שני מנהלי תוכן באותו שוכר לא יכולים להתווסף עם אותו email.
אתה לא יכול לשנות את ה-tenantId המשויך ל-Moderator.

דוגמת cURL ל-PATCH מנהל תוכן

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 מנהל תוכן

Copy

interface ModeratorPatchQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת PATCH מנהל תוכן

Copy

interface ModeratorPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'name-required' | 'email-required' | 'unexpected-param' | 'not-found';
    /** Included on failure. **/
    reason?: string
}

POST /api/v1/moderators

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

נתיב זה מספק את היכולת להוסיף Moderator יחיד.

ליצירת Moderator יש את ההגבלות הבאות:

תמיד יש לספק name ו-email. userId הוא אופציונלי.
אין לספק את הערכים הבאים בעת יצירת Moderator:
- acceptedInvite
- markReviewedCount
- deletedCount
- markedSpamCount
- approvedCount
- editedCount
- bannedCount
- verificationId
- createdAt
כאשר מצוין userId, המשתמש הזה חייב להתקיים.
כאשר מצוין userId, הוא חייב להשתייך לאותו tenantId שצוין בפרמטרי השאילתה.
שני מנהלי תוכן באותו שוכר לא יכולים להתווסף עם אותו email.

אנחנו יכולים ליצור Moderator למשתמש שאנחנו מכירים רק את האימייל שלו:

דוגמת cURL ליצירת מנהל תוכן באמצעות אימייל

Copy

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

או שאנחנו יכולים ליצור Moderator למשתמש השייך לשוכר שלנו, כדי לעקוב אחר סטטיסטיקות ניהול התוכן שלו:

דוגמת cURL ליצירת מנהל תוכן באמצעות משתמש שוכר

Copy

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

מבנה בקשת יצירת מנהל תוכן

Copy

interface ModeratorPostQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת יצירת מנהל תוכן

Copy

interface ModeratorPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'name-required' | 'email-required' | 'unexpected-param' | 'not-found'
    /** Included on failure. **/
    reason?: string
    moderator?: Moderator; // We return the complete created moderator on success.
}

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 תווים.

הערות:

אם משתמש עם האימייל שסופק כבר קיים, הוא יוזמן למתן את תגובות השוכר שלך.
אם משתמש עם האימייל שסופק לא קיים קישור ההזמנה ינחה אותו דרך יצירת החשבון שלו.
ההזמנה תפוג לאחר 30 יום.

אנחנו יכולים ליצור Moderator למשתמש שאנחנו מכירים רק את האימייל שלו:

דוגמת cURL להזמנת Moderator

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 ב-TenantName מזמין אותך להיות מנחה...

מבנה בקשת הזמנת Moderator

Copy

interface ModeratorSendInviteQueryParams {
    tenantId: string
    API_KEY: string
    /** The email sent to the user will appear to be sent from this name. **/
    fromName: string
}

מבנה תגובת הזמנת Moderator

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'
    /** Included on failure. **/
    reason?: string
}

DELETE /api/v1/moderators/:id

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

נתיב זה מספק הסרה של Moderator לפי מזהה.

דוגמת 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'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found'
    /** Included on failure. **/
    reason?: string
}

מבנה ספירת התראות

אובייקט NotificationCount מייצג את ספירת ההתראות שלא נקראו ומטא-נתונים עבור משתמש.

אם אין התראות שלא נקראו, לא יהיה NotificationCount עבור המשתמש.

אובייקטי NotificationCount נוצרים אוטומטית ולא ניתן ליצור אותם דרך ה-API. הם גם פגים לאחר שנה אחת.

אתה יכול לנקות את ספירת ההתראות שלא נקראו של משתמש על ידי מחיקת ה-NotificationCount שלו.

המבנה עבור אובייקט NotificationCount הוא כדלקמן:

מבנה NotificationCount

Copy

interface NotificationCount {
    id: string // user id
    count: number
    createdAt: string // date string
    expireAt: string // date string
}

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

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

נתיב זה מחזיר NotificationCount יחיד לפי מזהה משתמש. עם SSO, מזהה המשתמש הוא בפורמט <tenant id>:<user id>.

אם אין התראות שלא נקראו, לא יהיה NotificationCount - אז תקבל 404.

זה שונה מ-notifications/count בכך שהוא הרבה יותר מהיר, אך לא מאפשר סינון.

דוגמת cURL ל-NotificationCount לפי מזהה

Copy

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

מבנה בקשת NotificationCount

Copy

interface NotificationCountGetQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת NotificationCount

Copy

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

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

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

נתיב זה מוחק NotificationCount יחיד לפי מזהה משתמש. עם SSO, מזהה המשתמש הוא בפורמט <tenant id>:<user id>.

זה ינקה את ספירת ההתראות שלא נקראו של המשתמש (הפעמון האדום בווידג'ט התגובות יידהה והספירה תיעלם).

דוגמת cURL ל-DELETE 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'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'not-found'
    /** Included on failure. **/
    reason?: string
}

מבנה התראה

אובייקט Notification מייצג התראה עבור משתמש.

אובייקטי Notification נוצרים אוטומטית ולא ניתן ליצור אותם דרך ה-API. הם גם פגים לאחר שנה אחת. לא ניתן למחוק התראות. עם זאת, ניתן לעדכן אותן כדי להגדיר את viewed ל-false, וניתן לבצע שאילתה לפי viewed.

משתמש יכול גם לבחור לצאת מהתראות עבור תגובה ספציפית על ידי הגדרת optedOut בהתראה ל-true. ניתן להצטרף מחדש על ידי הגדרתו ל-false.

ישנם סוגי התראות שונים - בדוק את relatedObjectType ו-type.

הדרכים ליצירת התראות הן די גמישות וניתנות להפעלה על ידי תרחישים רבים (ראה NotificationType).

נכון להיום, קיום Notification לא באמת מרמז שאימייל נשלח או צריך להישלח. במקום זאת, ההתראות משמשות לפיד ההתראות ואינטגרציות קשורות.

המבנה עבור אובייקט Notification הוא כדלקמן:

מבנה התראה

Copy

enum NotificationObjectType {
    Comment = 0,
    Profile = 1,
    Tenant = 2
}
enum NotificationType {
    /** If someone replied to you. **/
    RepliedToMe = 0,
    /** If someone replied anywhere in a thread (even children of children) of a thread you commented on. **/
    RepliedTransientChild = 1,
    /** If your comment was up-voted. **/
    VotedMyComment = 2,
    /** If a new comment is left on the root of a page you're subscribed to. **/
    SubscriptionReplyRoot = 3,
    /** If someone commented on your profile. **/
    CommentedOnProfile = 4,
    /** If you have a DM. **/
    DirectMessage = 5,
    /** TrialLimits is for tenant users only. **/
    TrialLimits = 6,
    /** If you were @mentioned. **/
    Mentioned = 7
}
interface Notification {
    id: string
    tenantId: string
    /** With SSO, the user id is in the format `<tenant id>:<user id>`. **/
    userId?: string
    /** When working with SSO, you only have to worry about `userId`. **/
    anonUserId?: string
    /** urlId is almost always defined. It is only optional for tenant-level notifications, which are infrequent. **/
    urlId?: string
    /** URL is cached for quick navigation to the source of the notification. **/
    url?: string
    /** Page Title is cached for quick reading of notification source. **/
    pageTitle?: string
    relatedObjectType: NotificationObjectType
    /** For example, comment id. **/
    relatedObjectId: string
    viewed: boolean
    createdAt: string // date string
    type: NotificationType
    fromCommentId?: string
    fromVoteId?: string
    /** fromUserName and fromUserAvatarSrc are cached here for quick displaying of the notification. They are updated when the user is updated. **/
    fromUserName: string
    fromUserId: string
    fromUserAvatarSrc?: string
    /** Set this to true to stop getting notifications for this object. **/
    optedOut?: boolean
}

GET /api/v1/notifications

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

נתיב זה מחזיר עד 30 אובייקטי Notification ממוינים לפי createdAt, החדש ביותר ראשון.

אתה יכול לסנן לפי userId. עם SSO, מזהה המשתמש הוא בפורמט <tenant id>:<user id>.

דוגמת cURL להתראות לא נקראות למשתמש

Copy

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

מבנה בקשת התראות

Copy

interface NotificationsGetQueryParams {
    tenantId: string
    API_KEY: string
    /** Paginate by skipping records. **/
    skip?: number
    /** Filter by user. **/
    userId?: string
    /** Filter by urlId. **/
    urlId?: string
    /** Filter by source comment. **/
    fromCommentId?: string
    /** Filter by read/unread. **/
    viewed?: 'true' | 'false'
    /** Filter by type. **/
    type?: NotificationType
}

מבנה תגובת התראות

Copy

interface NotificationsGetResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Included on failure. **/
    reason?: string
    notifications?: Notification[]
}

GET /api/v1/notifications/count

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

נתיב זה מחזיר אובייקט המכיל את מספר ההתראות תחת פרמטר count.

הוא איטי יותר מ-/notification-count/ ועולה כפול בקרדיטים, אך מאפשר סינון על יותר ממדים.

אתה יכול לסנן לפי אותם פרמטרים כמו נקודת הקצה /notifications כמו userId. עם SSO, מזהה המשתמש הוא בפורמט <tenant id>:<user id>.

דוגמת cURL לספירת התראות שלא נקראו למשתמש

Copy

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

דוגמת cURL לספירת התראות שלא נקראו למשתמש עבור עמוד ספציפי

Copy

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

מבנה בקשת ספירת התראות

Copy

interface NotificationCountGetQueryParams {
    tenantId: string
    API_KEY: string
    /** Filter by user. **/
    userId?: string
    /** Filter by urlId. **/
    urlId?: string
    /** Filter by source comment. **/
    fromCommentId?: string
    /** Filter by read/unread. **/
    viewed?: 'true' | 'false'
    /** Filter by type. **/
    type?: NotificationType
}

מבנה תגובת ספירת התראות

Copy

interface NotificationCountGetResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Included on failure. **/
    reason?: string
    count?: number
}

PATCH /api/v1/notifications/:id

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

נקודת קצה API זו מספקת את היכולת לעדכן Notification לפי id.

לעדכון Notification יש את ההגבלות הבאות:

אתה יכול לעדכן רק את השדות הבאים:
- viewed
- optedOut

דוגמת cURL ל-PATCH Notification

Copy

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

מבנה בקשת PATCH Notification

Copy

interface NotificationPatchQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת PATCH Notification

Copy

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

מבנה עמוד

אובייקט Page מייצג את העמוד שתגובות רבות יכולות להשתייך אליו. יחס זה מוגדר על ידי urlId.

Page מאחסן מידע כגון כותרת העמוד, מספר התגובות, ו-urlId.

המבנה עבור אובייקט Page הוא כדלקמן:

מבנה עמוד

Copy

interface Page {
    id: string
    urlId: string
    url: string
    title?: string
    createdAt: string
    commentCount: number
    rootCommentCount: number
    /** Setting this to null means all SSO users can see the page. An empty list means it is closed to all users. **/
    accessibleByGroupIds?: string[] | null
    /** Is this page closed for new comments? **/
    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'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    pages: Page[]
}

טיפ מועיל

ה-API של Comment דורש urlId. אתה יכול לקרוא קודם ל-API של Pages, כדי לראות איך נראים ערכי urlId הזמינים לך.

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

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

עמודים בודדים יכולים להיות מאוחזרים לפי ה-urlId התואם שלהם. זה יכול להיות שימושי לחיפוש כותרות עמודים או ספירות תגובות.

דוגמת cURL ל-Page לפי URL ID

Copy

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

מבנה בקשת Page לפי URL ID

Copy

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

מבנה תגובת Page לפי URL ID

Copy

interface PagesResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id'
    /** Included on failure. **/
    reason?: string
    page?: Page[] | null
}

טיפ שימושי

זכור לקודד URI לערכים כמו ה-urlId.

PATCH /api/v1/pages/:id

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

נתיב זה מספק את היכולת לעדכן Page יחיד. התגובות המתאימות יעודכנו.

דוגמת cURL לעדכון עמוד

Copy

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

מבנה בקשת עדכון עמוד

Copy

interface PagePatchQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת עדכון עמוד

Copy

interface PagePatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    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'
    /** Included on failure. **/
    reason?: string
    user?: Page; // We return the complete updated page on success.
}

הערה

חלק מהפרמטרים באובייקט Page מתעדכנים אוטומטית. אלה הם מאפייני הספירות והכותרת. לא ניתן לעדכן ספירות דרך ה-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 ל-POST Page

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

מבנה בקשת POST Page

Copy

interface PagePostQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת POST Page

Copy

interface PagePostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    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';
    /** Included on failure. **/
    reason?: string
    /** The created page. **/
    page?: Page
}

DELETE /api/v1/pages/:id

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

נתיב זה מספק הסרה של עמוד בודד לפי מזהה.

שים לב שאינטראקציה עם ווידג'ט התגובות לעמוד עם אותו 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'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'page-does-not-exist'
    /** Included on failure. **/
    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-specific sync task. **/
    WP: 0,
    Webhook: 1
}
interface PendingWebhookEvent {
    id: string
    /** The comment id associated with the event. **/
    commentId: string
    /** The comment object for the event at the time of the event. We started adding these in Nov 2023. **/
    comment: Comment
    /** An external id that may be associated with the comment. **/
    externalId: string | null
    createdAt: Date
    tenantId: string
    attemptCount: number
    /** Set before first attempt, and after every failure. **/
    nextAttemptAt: Date
    /** Whether this is a creation, deletion, or update event... **/
    eventType: OutboundSyncEventType
    /** The type of sync to perform (WordPress, call API, etc). **/
    type: OutboundSyncType
    /** The domain that matched the comment. We use this domain to pick the API key. **/
    domain: string
    /** The last error that occurred. This type is untyped and is a "dump" of whatever happened. Usually it contains an object with statusCode, body, and a headers map. **/
    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
    /** Query for events with an attempt count greater than the specified number. **/
    attemptCountGT?: number
}

מבנה תגובת PendingWebhookEvent

Copy

interface PendingWebhookEventsGetResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Included on failure. **/
    reason?: string
    pendingWebhookEvents?: PendingWebhookEvent[]
}

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

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

נתיב זה מחזיר אובייקט המכיל את מספר אירועי ה-webhook הממתינים תחת פרמטר count.

אתה יכול לסנן לפי אותם פרמטרים כמו נקודת הקצה /pending-webhook-events

דוגמת cURL לספירת PendingWebhookEvent

Copy

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

מבנה בקשת ספירת PendingWebhookEvent

Copy

interface PendingWebhookEventsCountQueryParams {
    tenantId: string
    API_KEY: string
    commentId?: string
    externalId?: string
    eventType?: OutboundSyncEventType
    type?: OutboundSyncType
    domain?: string
    /** Query for events with an attempt count greater than the specified number. **/
    attemptCountGT?: number
}

מבנה תגובת ספירת PendingWebhookEvent

Copy

interface PendingWebhookEventsCountResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Included on failure. **/
    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 יחיד.

אם אתה צריך מחיקה בכמות, קרא ל-API של GET עם עימוד ואז קרא ל-API זה ברצף.

דוגמת cURL ל-DELETE PendingWebhookEvent

Copy

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

מבנה בקשת מחיקת PendingWebhookEvent

Copy

interface PendingWebhookEventDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת מחיקת PendingWebhookEvent

Copy

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

מבנה משתמש SSO

FastComments מספק פתרון SSO קל לשימוש. עדכון המידע של משתמש בעזרת האינטגרציה מבוססת HMAC הוא פשוט כמו לגרום למשתמש לטעון את הדף עם מטען מעודכן.

עם זאת, ייתכן ותרצו לנהל משתמש מחוץ לזרימה זו, כדי לשפר את העקביות של היישום שלכם.

ממשק ה-SSO User API מספק דרך לבצע CRUD על אובייקטים שאנו קוראים להם SSOUsers. אובייקטים אלה שונים ממשתמשים רגילים ונשמרים בנפרד למען בטיחות טיפוסים.

המבנה של אובייקט 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 Admins (נפרדים ממשתמשי SSO רגילים)
    isAdminAdmin?: boolean // הרשאת מנהל - משתמשי SSO עם דגל זה יחויבו כ-SSO Admins (נפרדים ממשתמשי SSO רגילים)
    isCommentModeratorAdmin?: boolean // הרשאת מודרציה - משתמשי SSO עם דגל זה יחויבו כ-SSO Moderators (נפרדים ממשתמשי SSO רגילים)
    /** אם null, בקרת גישה לא תיושם על המשתמש. אם רשימה ריקה, משתמש זה לא יוכל לראות שום דפים או @mention משתמשים אחרים. **/
    groupIds?: string[] | null
    createdFromSimpleSSO?: boolean
    /** אל תאפשר למשתמשים אחרים לראות את פעילות המשתמש הזה, כולל תגובות, בפרופיל שלו. ברירת המחדל היא true כדי לספק פרופילים מאובטחים כברירת מחדל. **/
    isProfileActivityPrivate?: boolean
    /** אל תאפשר למשתמשים אחרים להשאיר תגובות בפרופיל של המשתמש, או לראות תגובות פרופיל קיימות. ברירת המחדל false. **/
    isProfileCommentsPrivate?: boolean
    /** אל תאפשר למשתמשים אחרים לשלוח הודעות ישירות למשתמש זה. ברירת המחדל false. **/
    isProfileDMDisabled?: boolean
    karma?: number
    /** תצורה אופציונלית לסמלי המשתמש. **/
    badgeConfig?: {
        /** מערך מזהי סמלים שיוקצו למשתמש. מוגבל ל-30 סמלים. הסדר נשמר. אלו סמלים גלובליים הנראים בכל הדפים. **/
        badgeIds: string[]
        /** מערך מזהי סמלים המוגדרים לדף הנוכחי (urlId). סמלים אלו מוצגים רק בעמוד שבו הוקצו. **/
        pageBadgeIds?: string[]
        /** אם true, מחליף את כל הסמלים המוצגים הקיימים באלו שסופקו. סמלים גלובליים וסמלים ספציפיים לדף מוחלפים באופן עצמאי. אם false, מוסיף לסמלים הקיימים. **/
        override?: boolean
        /** אם true, מעדכן תכונות תצוגת הסמל מתצורת השוכר. **/
        update?: boolean
    }
}

חיוב עבור משתמשי SSO

משתמשי SSO מחוייבים באופן שונה בהתאם לדגלי ההרשאה שלהם:

משתמשי SSO רגילים: משתמשים ללא הרשאות מנהל או מודרציה מחוייבים כמשתמשי SSO רגילים
מנהלי SSO: משתמשים עם הדגלים isAccountOwner או isAdminAdmin מחוייבים בנפרד כ-מנהלי SSO (אותו שיעור כמו מנהלי שוכר רגילים)
מודרטורים של SSO: משתמשים עם הדגל isCommentModeratorAdmin מחוייבים בנפרד כ-מודרטורים של SSO (אותו שיעור כמו מודרטורים רגילים)

חשוב: כדי למנוע חיוב כפול, המערכת מבטלת כפילויות אוטומטית בין משתמשי SSO לבין משתמשי שוכר רגילים ומודרטורים על בסיס כתובת אימייל. אם למשתמש SSO יש את אותה כתובת אימייל כמו משתמש שוכר רגיל או מודרטור, הוא לא יחויב פעמיים.

בקרת גישה

משתמשים יכולים להיות מחולקים לקבוצות. לזה מיועד השדה groupIds, והוא אופציונלי.

@אזכורים

ברירת המחדל @mentions ישתמש ב-username כדי לחפש משתמשי SSO אחרים כאשר מקלידים את התו @. אם משתמשים ב-displayName, אז תוצאות התואמות ל-username יידחו כאשר יש התאמה ל-displayName, ותוצאות החיפוש של ה-@mention ישתמשו ב-displayName.

מנויים

ב-FastComments, משתמשים יכולים להירשם לדף על ידי לחיצה על סמל הפעמון בווידג'ט התגובות ולחיצה על הרשמה.

עם משתמש רגיל, אנו שולחים לו אימיילי התראות על בסיס הגדרות ההתראות שלו.

עם משתמשי SSO, אנו מפצלים זאת לתאימות לאחור. משתמשים יקבלו הודעות אימייל נוספות אלה רק אם תגדירו את optedInSubscriptionNotifications ל-true.

סמלים

ניתן להקצות סמלים למשתמשי SSO באמצעות השדה badgeConfig. סמלים הם אינדיקטורים ויזואליים המופיעים לצד שם המשתמש בתגובות.

badgeIds - מערך מזהי סמלים שיוקצו למשתמש. אלה סמלים גלובליים הנראים בכל הדפים. חייבים להיות מזהי סמלים תקפים שנוצרו בחשבון FastComments שלך. מוגבלים ל-30 סמלים.
pageBadgeIds - מערך מזהי סמלים אופציונלי המוגדר לדף הנוכחי (urlId). סמלים אלה מוצגים רק בדף שבו הוקצו. דפים שונים יכולים להכיל סמלים ספציפיים לדף שונים עבור אותו משתמש.
override - אם true, כל הסמלים המוצגים הקיימים יוחלפו באלו שסופקו. סמלים גלובליים וספציפיים לדף מוחלפים באופן עצמאי — החלפה של סמלים גלובליים לא משפיעה על סמלים ספציפיים לדף, ולהפך. אם false או לא צויין, הסמלים שסופקו יתווספו לסמלים הקיימים.
update - אם true, תכונות תצוגת הסמל יעודכנו מתוך תצורת השוכר כל פעם שהמשתמש ייכנס.

GET /api/v1/sso-users

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

נתיב זה מחזיר משתמשי SSO בעמודים של 100. עימוד מסופק על ידי פרמטר skip. משתמשים ממוינים לפי signUpDate ו-id שלהם.

דוגמת cURL ל-SSOUsers

Copy

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

מבנה בקשת SSOUsers

Copy

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

מבנה תגובת SSOUsers

Copy

interface SSOUsersResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    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 יחיד לפי המזהה שלו.

דוגמת cURL ל-SSOUser לפי מזהה

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'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'user-does-not-exist'
    /** Included on failure. **/
    reason?: string
    user: SSOUser
}

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

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

נתיב זה מחזיר משתמש SSO יחיד לפי האימייל שלו.

דוגמת cURL ל-SSOUser לפי אימייל

Copy

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

מבנה בקשת SSOUser

Copy

interface SSOUserRequestByEmailQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת SSOUser

Copy

interface SSOUserByEmailResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-email' | 'user-does-not-exist'
    /** Included on failure. **/
    reason?: string
    user: SSOUser
}

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

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

נתיב זה מספק את היכולת לעדכן משתמש SSO יחיד.

דוגמת cURL לעדכון SSOUser

Copy

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

מבנה בקשת עדכון SSOUser

Copy

interface SSOUserPatchQueryParams {
    tenantId: string
    API_KEY: string
    /** When email or username is changed, you can set this to true to also update the user's comments. This will double the credit cost. **/
    updateComments: 'true' | 'false'
}

מבנה תגובת עדכון SSOUser

Copy

interface SSOUserPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-does-not-exist'
    /** Included on failure. **/
    reason?: string
    user?: SSOUser; // We return the complete updated user on success.
}

POST /api/v1/sso-users

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

נתיב זה מספק יצירה של משתמש SSO יחיד.

ניסיון ליצור שני משתמשים עם אותו מזהה יגרום לשגיאה.

דוגמת cURL ליצירת SSOUser

Copy

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

בדוגמה זו אנחנו מציינים groupIds לבקרת גישה, אבל זה אופציונלי.

מבנה בקשת יצירת SSOUser

Copy

interface SSOUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת יצירת SSOUser

Copy

interface SSOUserPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-exists'
    /** Included on failure. **/
    reason?: string
    user?: SSOUser; // We return the created user on success.
}

הערת אינטגרציה

נתונים שמועברים על ידי ה-API יכולים להידרס פשוט על ידי העברת מטען HMAC של משתמש SSO שונה. לדוגמה, אם אתה מגדיר שם משתמש דרך ה-API, אבל אז מעביר שם אחר דרך זרימת ה-SSO בטעינת העמוד, אנחנו נעדכן אוטומטית את שם המשתמש שלו.

אנחנו לא נעדכן פרמטרי משתמש בזרימה זו אלא אם כן אתה מציין אותם במפורש או מגדיר אותם ל-null (לא undefined).

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

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

נתיב זה מספק את היכולת לעדכן משתמש SSO יחיד.

דוגמת cURL לעדכון SSOUser

Copy

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

בדוגמה זו אנו מציינים groupIds לבקרת גישה, אך זה אופציונלי.

מבנה בקשת עדכון SSOUser

Copy

interface SSOUserPutQueryParams {
    tenantId: string
    API_KEY: string
    /** When email or username is changed, you can set this to true to also update the user's comments. This will double the credit cost. **/
    updateComments: 'true' | 'false'
}

מבנה תגובת עדכון SSOUser

Copy

interface SSOUserPutResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-exists'
    /** Included on failure. **/
    reason?: string
    user?: SSOUser; // We return the update user on success.
}

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

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

נתיב זה מספק הסרה של משתמש SSO יחיד לפי המזהה שלו.

שים לב שטעינת ווידג'ט התגובות שוב עם מטען עבור משתמש זה פשוט תיצור מחדש את המשתמש בצורה חלקה.

מחיקת התגובות של המשתמש אפשרית באמצעות פרמטר השאילתה deleteComments. שים לב שאם זה true:

כל התגובות של המשתמש יימחקו בזמן אמת.
כל התגובות ילדים (עכשיו יתומות) יימחקו או יאונמו בהתבסס על קונפיגורציית העמוד המשויכת לכל תגובה. לדוגמה אם מצב מחיקת שרשור הוא "anonymize", אז תשובות יישארו, ותגובות המשתמש יאונמו. זה חל רק כאשר commentDeleteMode הוא Remove (ערך ברירת המחדל).
ה-creditsCost הופך ל-2.

תגובות מאונמות

אתה יכול לשמור את התגובות של המשתמש אבל פשוט לאנונם אותן על ידי הגדרת commentDeleteMode=1.

אם התגובות של המשתמש מאונמות אז הערכים הבאים מוגדרים ל-null:

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

isDeleted ו-isDeletedUser מוגדרים ל-true.

בעת רינדור, ווידג'ט התגובות ישתמש ב-DELETED_USER_PLACEHOLDER (ברירת מחדל: "[deleted]") לשם המשתמש ו-DELETED_CONTENT_PLACEHOLDER לתגובה. ניתן להתאים אישית אלה דרך ממשק המשתמש של התאמת הווידג'ט.

דוגמאות

דוגמת cURL להסרת SSOUser

Copy

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

מבנה בקשת הסרת SSOUser

Copy

enum SSOUserCommentDeleteMode {
    Remove = 0, // default
    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
}

מבנה תגובת הסרת SSOUser

Copy

interface SSOUsersResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'user-does-not-exist'
    /** Included on failure. **/
    reason?: string
    user?: SSOUser; // We return the removed user on success.
}

מבנה מנוי

אובייקט Subscription מייצג מנוי עבור משתמש.

אובייקטי Subscription נוצרים כאשר משתמש לוחץ על פעמון ההתראות בווידג'ט התגובות ולוחץ על "הירשם לעמוד זה".

ניתן גם ליצור מנויים דרך ה-API.

קיום אובייקט Subscription גורם ליצירת אובייקטי Notification, ושליחת אימיילים, כאשר תגובות חדשות נשארות בשורש העמוד המשויך שה-Subscription הוא עבורו. שליחת אימיילים תלויה בסוג המשתמש. למשתמשים רגילים זה תלוי ב-optedInNotifications. למשתמשי SSO זה תלוי ב-optedInSubscriptionNotifications. שים לב שלחלק מהאפליקציות אולי אין את הרעיון של עמוד נגיש לאינטרנט, במקרה זה פשוט הגדר את urlId ל- מזהה הפריט שאתה נרשם אליו (אותו ערך עבור urlId שהיית מעביר לווידג'ט התגובות).

המבנה עבור אובייקט Subscription הוא כדלקמן:

מבנה מנוי

Copy

interface Subscription {
    id: string
    tenantId: string
    /** With SSO, the user id is in the format `<tenant id>:<user id>`. **/
    userId: string
    anonUserId?: string
    urlId: string
    url?: string
    pageTitle?: string
    createdAt: string // date string
}

GET /api/v1/subscriptions/:id

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

נתיב זה מחזיר עד 30 אובייקטי Subscription ממוינים לפי createdAt, החדש ביותר ראשון.

אתה יכול לסנן לפי userId. עם SSO, מזהה המשתמש הוא בפורמט <tenant id>:<user id>.

דוגמת cURL למנויים למשתמש

Copy

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

מבנה בקשת מנויים

Copy

interface SubscriptionsGetQueryParams {
    tenantId: string
    API_KEY: string
    /** Paginate by skipping records. **/
    skip?: number
    /** Filter by user. **/
    userId?: string
}

מבנה תגובת מנויים

Copy

interface SubscriptionsGetResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Included on failure. **/
    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'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'unauthorized' | 'not-found';
    /** Included on failure. **/
    reason?: string
}

DELETE /api/v1/subscriptions/:id

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

נתיב זה מוחק אובייקט Subscription יחיד לפי מזהה.

דוגמת cURL להסרת Subscription

Copy

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

מבנה בקשת הסרת Subscription

Copy

interface SubscriptionsDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת הסרת Subscription

Copy

interface SubscriptionDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Included on failure. **/
    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 for billing. **/
    ignored: boolean
}

GET /api/v1/tenant-daily-usage

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

נתיב זה מאפשר חיפוש שימוש של שוכר לפי שנה, חודש ויום. ניתן להחזיר עד 365 אובייקטים, והעלות היא 1 קרדיט API לכל 10 אובייקטים.

אובייקטי תגובה ממוינים לפי התאריך שבו נוצרו (הישן ביותר קודם).

דוגמת cURL לחיפוש TenantDailyUsage

Copy

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

מבנה בקשת TenantDailyUsage

Copy

interface TenantDailyUsageQueryParams {
    tenantId: string
    API_KEY: string
    /** Based on UTC. **/
    yearNumber?: number
    /** Zero-based. Based on UTC. **/
    monthNumber?: number
    /** One-based. Based on UTC. **/
    dayNumber?: number
}

מבנה תגובת TenantDailyUsage

Copy

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

מבנה שוכר

Tenant מגדיר לקוח של FastComments.com. ניתן ליצור אותם דרך ה-API על ידי שוכרים עם גישת white labeling. שוכרי white labeled לא יכולים ליצור שוכרי white labeled אחרים (רק רמה אחת של קינון מותרת).

המבנה עבור אובייקט Tenant הוא כדלקמן:

מבנה שוכר

Copy

export enum SiteType {
    Unknown = 0,
    WordPress = 1
}
/** This can also be handled via the DomainConfig API. **/
export interface TenantDomainConfig {
    domain: string
    emailFromName?: string
    emailFromEmail?: string
    createdAt?: string,
    siteType?: FastCommentsSiteType, // you probably want Unknown
    logoSrc?: string, // raw image path
    logoSrc100px?: string, // resized for thumbnails
    footerUnsubscribeURL?: string,
    emailHeaders?: Record<string, string>,
    disableUnsubscribeLinks?: boolean,
    dkim?: {
        domainName: string,
        keySelector: string,
        privateKey: string
    }
}
export interface TenantBillingInfo {
    name: string
    address: string
    city: string
    state: string
    zip: string
    country: string
}
export enum TenantPaymentFrequency {
    Monthly = 0,
    Annually = 1
}
export interface Tenant {
    id: string
    name: string
    email?: string
    signUpDate: number; // number due to "legacy" reasons
    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 - Is calculated based on packageId. **/
    hasFlexPricing?: boolean
    /** @readonly **/
    flexLastBilledAmount?: number
    /** @readonly - Is calculated based on packageId. **/
    hasAuditing?: boolean
    /** You can store a key value pair with the tenant which you can use to query. Keys cannot contain "." or "$", or be longer than 100 chars. Values may not be longer than 2k chars. **/
    meta?: Record<string, string | null>
}

GET /api/v1/tenants/:id

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

נתיב זה מחזיר שוכר יחיד לפי מזהה.

דוגמת cURL לשוכר לפי מזהה

Copy

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

מבנה בקשת שוכר

Copy

interface TenantByIdQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת שוכר

Copy

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

GET /api/v1/tenants

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

API זה מחזיר שוכרים המנוהלים על ידי השוכר שלך.

עימוד מסופק על ידי פרמטר השאילתה skip. שוכרים מוחזרים בעמודים של 100, מסודרים לפי signUpDate, ו-id.

העלות מבוססת על מספר השוכרים שהוחזרו, בעלות של 1 קרדיט לכל 10 שוכרים שהוחזרו.

דוגמת cURL ל-Tenant

Copy

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

אתה יכול להגדיר פרמטרי meta על אובייקטי ה-Tenant ולחפש שוכרים תואמים. לדוגמה, עבור המפתח someKey וערך המטא some-value, אנחנו יכולים לבנות אובייקט JSON עם זוג מפתח/ערך זה ואז לקודד אותו כ-URI כפרמטר שאילתה לסינון:

דוגמת cURL לשאילתת Tenant לפי Meta

Copy

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

מבנה בקשת Tenant

Copy

interface TenantsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The number of tenants to skip for pagination. **/
    skip?: number
    /** Filter by meta params. **/
    meta?: string
}

מבנה תגובת Tenant

Copy

interface TenantsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    tenants?: Tenant[]
}

POST /api/v1/tenants

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

נתיב זה מספק את היכולת להוסיף Tenant יחיד.

ליצירת Tenant יש את ההגבלות הבאות:

נדרש name.
נדרש domainConfiguration.
הערכים הבאים לא ניתנים לספק בעת יצירת Tenant:
- hasFlexPricing
- lastBillingIssueReminderDate
- flexLastBilledAmount
ה-signUpDate לא יכול להיות בעתיד.
ה-name לא יכול להיות ארוך מ-200 תווים.
ה-email לא יכול להיות ארוך מ-300 תווים.
ה-email חייב להיות ייחודי בכל שוכרי FastComments.com.
לא ניתן ליצור שוכרים אם לשוכר האב אין TenantPackage תקף מוגדר.
- אם השוכר שלך נוצר דרך FastComments.com, זו לא אמורה להיות בעיה.
לא ניתן ליצור יותר שוכרים מהמוגדר תחת maxWhiteLabeledTenants בחבילה שלך.
חייב לציין את פרמטר השאילתה tenantId שהוא המזהה של שוכר האב שלך עם תיוג לבן מופעל.

אנחנו יכולים ליצור Tenant עם רק כמה פרמטרים:

דוגמת cURL ליצירת Tenant

Copy

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

מבנה בקשת יצירת Tenant

Copy

interface TenantPostQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת יצירת Tenant

Copy

interface TenantPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    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'
    /** Included on failure. **/
    reason?: string
    tenant?: Tenant; // We return the complete created tenant on success.
}

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 תווים.
ה-email לא יכול להיות ארוך מ-300 תווים.
ה-email חייב להיות ייחודי בכל שוכרי FastComments.com.
כאשר מגדירים billingInfoValid ל-true, יש לספק billingInfo באותה בקשה.
לא ניתן לעדכן את ה-packageId המשויך לשוכר שלך עצמו.
לא ניתן לעדכן את ה-paymentFrequency המשויך לשוכר שלך עצמו.

דוגמת cURL ל-PATCH Tenant

Copy

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

מבנה בקשת PATCH Tenant

Copy

interface TenantPatchQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת PATCH Tenant

Copy

interface TenantPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    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';
    /** Included on failure. **/
    reason?: string
}

DELETE /api/v1/tenants/:id

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

נתיב זה מספק הסרה של Tenant וכל הנתונים המשויכים (משתמשים, תגובות, וכו') לפי מזהה.

ההגבלות הבאות קיימות סביב הסרת שוכרים:

השוכר חייב להיות שלך, או שוכר white labeled שאתה מנהל.
פרמטר השאילתה sure חייב להיות מוגדר ל-true.

דוגמת cURL להסרת שוכר

Copy

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

מבנה בקשת הסרת שוכר

Copy

interface TenantDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת הסרת שוכר

Copy

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

מבנה חבילת שוכר

TenantPackage מגדיר מידע על חבילה זמינה ל-Tenant. לשוכר עשויות להיות חבילות רבות זמינות, אבל רק אחת בשימוש בזמן נתון.

לא ניתן להשתמש ב-Tenant עבור מוצרים כלשהם עד ש-packageId שלו מצביע על TenantPackage חוקי.

ישנם שני סוגים של אובייקטי TenantPackage:

חבילות מחיר קבוע - שבהן hasFlexPricing הוא false.
תמחור גמיש - שבו hasFlexPricing הוא true.

בשני המקרים מוגדרות מגבלות על החשבון שמשתמש בחבילה, אולם עם Flex השוכר מחויב במחיר בסיס בתוספת מה שהשתמש, המוגדר על ידי פרמטרי flex*.

לשוכר עשויות להיות מספר חבילות שוכר ויכולת לשנות את החבילה בעצמו מ-דף פרטי החיוב.

אם אתה מתכנן לטפל בחיוב עבור שוכרים בעצמך, עדיין תצטרך להגדיר חבילה לכל שוכר כדי להגדיר את המגבלות שלהם. פשוט הגדר 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 // Cost per regular SSO user (without admin/moderator permissions)
    flexSSOUserUnit?: null
    flexAPICreditCostCents?: null
    flexAPICreditUnit?: null
    flexModeratorCostCents?: null
    flexModeratorUnit?: null
    flexAdminCostCents?: null
    flexAdminUnit?: null
    flexDomainCostCents?: null
    flexDomainUnit?: null
    flexSSOAdminCostCents?: null // Cost per SSO user with admin permissions (isAccountOwner or isAdminAdmin flags)
    flexSSOAdminUnit?: null
    flexSSOModeratorCostCents?: null // Cost per SSO user with moderator permissions (isCommentModeratorAdmin flag)
    flexSSOModeratorUnit?: null
    flexMinimumCostCents?: null
}

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

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

נתיב זה מחזיר חבילת שוכר יחידה לפי מזהה.

דוגמת cURL ל-TenantPackage לפי מזהה

Copy

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

מבנה בקשת TenantPackage

Copy

interface TenantPackageByIdQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת TenantPackage

Copy

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

GET /api/v1/tenant-packages

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

API זה משתמש בעימוד, המסופק על ידי פרמטר השאילתה skip. TenantPackages מוחזרים בעמודים של 100, מסודרים לפי createdAt ו-id.

העלות מבוססת על מספר חבילות השוכר שהוחזרו, בעלות של 1 קרדיט לכל 10 חבילות שוכר שהוחזרו.

דוגמת cURL ל-TenantPackage

Copy

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

מבנה בקשת TenantPackage

Copy

interface TenantPackagesRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The number of tenant packages to skip for pagination. **/
    skip?: number
}

מבנה תגובת TenantPackage

Copy

interface TenantPackagesResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    tenantPackages?: TenantPackage[]
}

POST /api/v1/tenant-packages

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

נתיב זה מספק את היכולת להוסיף TenantPackage יחיד.

ליצירת TenantPackage יש את ההגבלות הבאות:

הפרמטרים הבאים נדרשים:
- name
- tenantId
- monthlyCostUSD - יכול להיות null.
- yearlyCostUSD - יכול להיות null.
- maxMonthlyPageLoads
- maxMonthlyAPICredits
- maxMonthlyComments
- maxConcurrentUsers
- maxTenantUsers
- maxSSOUsers
- maxModerators
- maxDomains
- hasDebranding
- forWhoText
- featureTaglines
- hasFlexPricing - אם true, אז כל פרמטרי ה-flex* נדרשים.
ה-name לא יכול להיות ארוך מ-50 תווים.
כל פריט forWhoText לא יכול להיות ארוך מ-200 תווים.
כל פריט featureTaglines לא יכול להיות ארוך מ-100 תווים.
ה-TenantPackage חייב להיות "קטן יותר" מהשוכר האב. לדוגמה, כל פרמטרי ה-max* חייבים להיות בעלי ערכים נמוכים יותר מהשוכר האב.
שוכר עם תיוג לבן יכול להיות לו מקסימום חמש חבילות.
רק שוכרים עם גישה לתיוג לבן יכולים ליצור TenantPackage.
לא ניתן להוסיף חבילות לשוכר שלך עצמו. :)

אנחנו יכולים ליצור TenantPackage כדלקמן:

דוגמת cURL ליצירת TenantPackage דרך אימייל

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'
    /** Included on failure. **/
    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'
    /** Included on failure. **/
    reason?: string
    tenantPackage?: TenantPackage; // We return the complete created tenant package on success.
}

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

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

נקודת קצה API זו מספקת את היכולת לעדכן TenantPackage לפי id.

לעדכון TenantPackage יש את ההגבלות הבאות:

אם אתה מגדיר hasFlexPricing ל-true, אז כל פרמטרי ה-flex* נדרשים באותה בקשה.
ה-name לא יכול להיות ארוך מ-50 תווים.
כל פריט forWhoText לא יכול להיות ארוך מ-200 תווים.
כל פריט featureTaglines לא יכול להיות ארוך מ-100 תווים.
ה-TenantPackage חייב להיות "קטן יותר" מהשוכר האב. לדוגמה, כל פרמטרי ה-max* חייבים להיות בעלי ערכים נמוכים יותר מהשוכר האב.
לא ניתן לשנות את ה-tenantId המשויך ל-TenantPackage.

דוגמת cURL ל-PATCH TenantPackage

Copy

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

מבנה בקשת PATCH TenantPackage

Copy

interface TenantPackagePatchQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת PATCH TenantPackage

Copy

interface TenantPackagePatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    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';
    /** Included on failure. **/
    reason?: string
}

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

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

נתיב זה מספק הסרה של TenantPackage לפי מזהה.

לא ניתן להסיר TenantPackage שנמצא בשימוש (ה-packageId של שוכר מצביע על החבילה). עדכן את ה-Tenant קודם.

דוגמת cURL להסרת TenantPackage

Copy

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

מבנה בקשת הסרת TenantPackage

Copy

interface TenantPackageDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת הסרת TenantPackage

Copy

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

מבנה משתמש שוכר

TenantUser מגדיר User המנוהל על ידי שוכר ספציפי. החשבון שלו בשליטה מלאה של השוכר שהוא משויך אליו, והחשבון שלו ניתן לעדכון או מחיקה דרך ממשק המשתמש או ה-API.

משתמשי שוכר יכולים להיות מנהלים עם כל ההרשאות וגישה ל-Tenant, או שהם יכולים להיות מוגבלים להרשאות ספציפיות ל ניהול תגובות, גישה למפתחות API, וכו'.

המבנה עבור אובייקט TenantUser הוא כדלקמן:

מבנה TenantUser

Copy

/** This is for notifications. **/
export enum UserDigestEmailFrequency {
    Disabled = -1,
    Daily = 0,
    Weekly = 1,
    Monthly = 2
}
export interface TenantUser {
    id: string
    tenantId: string
    username: string
    /** A link to the commenter's blog, for example. **/
    websiteUrl?: string
    email: string
    signUpDate: number
    createdFromUrlId: string
    createdFromTenantId: string
    verified: boolean
    loginCount: number
    optedInNotifications: boolean
    optedInTenantNotifications: boolean
    hideAccountCode: boolean
    avatarSrc?: string
    /** Does the user receive help requests from commenters? **/
    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 יחיד לפי מזהה.

דוגמת cURL ל-TenantUser לפי מזהה

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'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'unauthorized'
    /** Included on failure. **/
    reason?: string
    tenantUser?: TenantUser
}

GET /api/v1/tenant-users

Resource: TenantUser as GET /api/v1/tenant-users Credit Cost: 1

API זה משתמש בעימוד, המסופק על ידי פרמטר השאילתה skip. TenantUsers מוחזרים בעמודים של 100, מסודרים לפי signUpDate, username ו-id.

העלות מבוססת על מספר משתמשי השוכר שהוחזרו, בעלות של 1 קרדיט לכל 10 משתמשי שוכר שהוחזרו.

דוגמת cURL ל-TenantUser

Copy

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

מבנה בקשת TenantUser

Copy

interface TenantUsersRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The number of tenant users to skip for pagination. **/
    skip?: number
}

מבנה תגובת TenantUser

Copy

interface TenantUsersResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    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 במקום זאת.
לא ניתן ליצור יותר משתמשי שוכר מהמוגדר תחת 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'
    /** Included on failure. **/
    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'
    /** Included on failure. **/
    reason?: string
    tenantUser?: TenantUser; // We return the complete created tenant user on success.
}

Resource: TenantUser as POST /api/v1/tenant-users/:id/send-login-link Credit Cost: 10

נתיב זה מספק את היכולת לשלוח קישור התחברות ל-TenantUser יחיד.

שימושי בעת יצירת משתמשים בכמות ללא צורך להנחות אותם כיצד להתחבר ל-FastComments.com. זה פשוט ישלח להם "קישור קסם" להתחברות שפג תוקף לאחר 30 יום.

ההגבלות הבאות קיימות לשליחת קישור התחברות ל-TenantUser:

ה-TenantUser חייב כבר להתקיים.
חייבת להיות לך גישה לנהל את ה-Tenant שאליו ה-TenantUser שייך.

אנחנו יכולים לשלוח קישור התחברות ל-TenantUser כדלקמן:

דוגמת cURL לקישור התחברות TenantUser

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/tenant-users/xyz/send-login-link?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json'

זה ישלח אימייל כמו Bob ב-TenantName מזמין אותך להיות מנחה...

מבנה בקשת קישור התחברות TenantUser

Copy

interface TenantUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת קישור התחברות TenantUser

Copy

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

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

Resource: TenantUser as PATCH /api/v1/tenant-users/:id Credit Cost: 1

נתיב זה מספק את היכולת לעדכן TenantUser יחיד.

לעדכון TenantUser יש את ההגבלות הבאות:

ה-signUpDate לא יכול להיות בעתיד.
ה-locale חייב להיות ברשימת לוקלים נתמכים.
ה-username חייב להיות ייחודי בכל FastComments.com. אם זו בעיה, אנו מציעים להשתמש ב-SSO במקום זאת.
ה-email חייב להיות ייחודי בכל FastComments.com. אם זו בעיה, אנו מציעים להשתמש ב-SSO במקום זאת.
לא ניתן לעדכן את ה-tenantId של משתמש.

אנחנו יכולים ליצור TenantUser כדלקמן

דוגמת cURL לעדכון TenantUser

Copy

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

מבנה בקשת עדכון TenantUser

Copy

interface TenantUserPatchQueryParams {
    tenantId: string
    API_KEY: string
    /** When email or username is changed, you can set this to true to also update the user's comments. This will double the credit cost. **/
    updateComments: 'true' | 'false'
}

מבנה תגובת עדכון TenantUser

Copy

interface TenantUserPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    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'
    /** Included on failure. **/
    reason?: string
}

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

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

נתיב זה מספק הסרה של TenantUser לפי מזהה.

מחיקת התגובות של המשתמש אפשרית באמצעות פרמטר השאילתה deleteComments. שים לב שאם זה true:

כל התגובות של המשתמש יימחקו בזמן אמת.
כל התגובות ילדים (עכשיו יתומות) יימחקו או יאונמו בהתבסס על קונפיגורציית העמוד המשויכת לכל תגובה. לדוגמה אם מצב מחיקת שרשור הוא "anonymize", אז תשובות יישארו, ותגובות המשתמש יאונמו. זה חל רק כאשר commentDeleteMode הוא Remove (ערך ברירת המחדל).
ה-creditsCost הופך ל-2.

תגובות מאונמות

אתה יכול לשמור את התגובות של המשתמש אבל פשוט לאנונם אותן על ידי הגדרת commentDeleteMode=1.

אם התגובות של המשתמש מאונמות אז הערכים הבאים מוגדרים ל-null:

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

isDeleted ו-isDeletedUser מוגדרים ל-true.

דוגמאות

דוגמת 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, // default
    Anonymize = 1
}
interface TenantUserDeleteQueryParams {
    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?: TenantUserCommentDeleteMode
}

מבנה תגובת הסרת TenantUser

Copy

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

מבנה משתמש

User הוא אובייקט המייצג מכנה משותף של כל המשתמשים.

זכור שב-FastComments יש לנו מספר מקרי שימוש שונים למשתמשים:

SSO מאובטח
SSO פשוט
משתמשי שוכר (לדוגמה: מנהלים)
מגיבים

API זה מיועד למגיבים ולמשתמשים שנוצרו דרך SSO פשוט. בעצם, כל משתמש שנוצר דרך האתר שלך ניתן לגישה דרך API זה. ניתן לאחזר גם משתמשי שוכר בדרך זו, אך תקבל מידע נוסף על ידי אינטראקציה עם ה-API /tenant-users/.

עבור SSO מאובטח אנא השתמש ב-API /sso-users/.

לא ניתן לעדכן סוגים אלה של משתמשים. הם יצרו את החשבון שלהם דרך האתר שלך, אז אנו מספקים גישה בסיסית לקריאה בלבד, אבל לא ניתן לבצע שינויים. אם אתה רוצה לקבל זרימה כזו - אתה צריך להגדיר SSO מאובטח.

המבנה עבור אובייקט User הוא כדלקמן:

מבנה User

Copy

export interface User {
    /** This is also the id used as userId on comment objects. **/
    id: string
    username: string
    /** A link to the commenter's blog, for example. **/
    websiteUrl?: string
    email: string
    signUpDate: number
    createdFromUrlId: string
    createdFromTenantId: string
    avatarSrc?: string
    locale: FastCommentsLocale
    displayLabel?: string
    karma?: number
}

GET /api/v1/users/:id

Resource: User as GET /api/v1/users/:id Credit Cost: 1

נתיב זה מחזיר User יחיד לפי מזהה.

דוגמת cURL ל-User לפי מזהה

Copy

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

מבנה בקשת User

Copy

interface UserByIdQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת User

Copy

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

מבנה הצבעה

אובייקט Vote מייצג הצבעה שהושארה על ידי משתמש.

היחס בין תגובות להצבעה מוגדר באמצעות commentId.

המבנה עבור אובייקט Vote הוא כדלקמן:

מבנה הצבעה

Copy

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

GET /api/v1/votes

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

יש לאחזר הצבעות לפי urlId.

סוגי הצבעות

ישנם שלושה סוגי הצבעות:

הצבעות מאומתות, שמיושמות על התגובה המתאימה. אתה יכול ליצור אלה דרך API זה.
הצבעות מאומתות, שהן ממתינות לאימות, ולכן עדיין לא מיושמות על התגובה. אלה נוצרות כאשר משתמש משתמש במנגנון התחבר כדי להצביע של FastComments.com.
הצבעות אנונימיות, שמיושמות על התגובה המתאימה. אלה נוצרות יחד עם תגובות אנונימיות.

אלה מוחזרות ברשימות נפרדות ב-API כדי להפחית בלבול.

דוגמת cURL להצבעות

Copy

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

מבנה בקשת הצבעות

Copy

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

מבנה תגובת הצבעות

Copy

interface VotesResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id'
    /** Included on failure. **/
    reason?: string
    /** Authorized, verified votes, applied to their corresponding comments. **/
    appliedAuthorizedVotes: Vote[]
    /** Anonymous votes, applied to their corresponding comments. **/
    appliedAnonymousVotes: Vote[]
    /** Votes pending verification, not yet applied to their corresponding comments. **/
    pendingVotes: Vote[]
}

הערות הצבעות אנונימיות

שים לב שהצבעות אנונימיות שנוצרו דרך API זה יופיעו ברשימת appliedAuthorizedVotes. הן נחשבות מאושרות מכיוון שנוצרו דרך ה-API עם מפתח API.

מבנה appliedAnonymousVotes הוא להצבעות שנוצרו ללא אימייל, מפתח API, וכו'.

GET /api/v1/votes/for-user

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

מאפשר אחזור הצבעות שהושארו על ידי משתמש ב-urlId נתון. מקבל userId שיכול להיות כל משתמש FastComments.com או SSO User.

זה שימושי אם אתה רוצה להראות אם משתמש הצביע על תגובה. בעת אחזור תגובות, פשוט קרא ל-API זה באותו זמן עבור המשתמש עם אותו urlId.

אם אתה משתמש בהצבעה אנונימית אז תרצה להעביר anonUserId במקום.

דוגמת cURL להצבעות עבור משתמש

Copy

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

דוגמת cURL להצבעות עבור משתמש אנונימי

Copy

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

שים לב שהצבעות אנונימיות יופיעו ברשימת appliedAuthorizedVotes. הן נחשבות מורשות מכיוון שנוצרו דרך ה-API עם מפתח API.

מבנה בקשת הצבעות עבור משתמש

Copy

interface VotesForUserRequestQueryParams {
    tenantId: string
    API_KEY: string
    urlId: string
    userId?: string
    anonUserId?: string
}

מבנה תגובת הצבעות עבור משתמש

Copy

interface VotesForUserResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'invalid-user-id'
    /** Included on failure. **/
    reason?: string
    /** Authorized, verified votes, applied to their corresponding comments. **/
    appliedAuthorizedVotes: Vote[]
    /** Votes pending verification, not yet applied to their corresponding comments. **/
    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'
    /** Included on failure. **/
    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'
    /** Included on failure. **/
    reason?: string
    voteId?: string
}

יצירת הצבעות אנונימיות

ניתן ליצור הצבעות אנונימיות על ידי הגדרת anonUserId בפרמטרי השאילתה במקום userId.

מזהה זה לא חייב להתאים לאובייקט משתמש בשום מקום (ומכאן אנונימי). זה פשוט מזהה עבור הסשן, כך שתוכל לאחזר הצבעות שוב באותו סשן, כדי לבדוק אם הצביעו על תגובה.

אם אין לך דבר כזה כמו "סשנים אנונימיים" כמו ל-FastComments - אתה יכול פשוט להגדיר זאת למזהה אקראי, כמו UUID (אם כי אנחנו מעריכים מזהים קטנים יותר לחיסכון במקום).

הערות נוספות

API זה מציית להגדרות ברמת השוכר. לדוגמה, אם אתה משבית הצבעות לעמוד נתון, וניסית ליצור הצבעה דרך ה-API, זה ייכשל עם קוד שגיאה voting-disabled.
API זה הוא בזמן אמת כברירת מחדל.
API זה יעדכן את votes של Comment המתאים.

DELETE /api/v1/votes/:id

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

נתיב זה מספק את היכולת למחוק Vote יחיד.

דוגמת cURL למחיקת הצבעה

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'

מבנה בקשת מחיקת הצבעה

Copy

interface VoteDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת מחיקת הצבעה

Copy

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

הערות:

API זה מציית להגדרות ברמת השוכר. לדוגמה, אם אתה משבית הצבעות לעמוד נתון, וניסית ליצור הצבעה דרך ה-API, זה ייכשל עם קוד שגיאה voting-disabled.
API זה הוא בזמן אמת כברירת מחדל.
API זה יעדכן את votes של Comment המתאים.

מבנה הגדרות דומיין

אובייקט DomainConfig מייצג תצורה עבור דומיין של שוכר.

המבנה של האובייקט DomainConfig הוא כדלקמן:

מבנה תצורת הדומיין

Copy

interface DomainConfig {
    /** דומיין, לא URL, כמו "fastcomments.com" או "www.example.com". ניתן לכלול תת‑דומיין אם רוצים להגביל לתת‑דומיין. מקסימום 1000 תווים. **/
    domain: string
    /** השם שמופיע בשדה From בעת שליחת אימיילים. **/
    emailFromName?: string
    /** כתובת ה-From המושמשת לשליחת אימיילים. ודאו ש-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
    /** מצביע המפתח (selector) של DKIM לשימוש. **/
    keySelector: string
    /** המפתח הציבורי בפורמט PEM. מוחזר בתגובות GET. **/
    publicKey: string
    /** @deprecated לא מוחזר עוד בתגובות ה-API. מתקבל בכתיבה עבור תאימות לאחור. **/
    privateKey?: string
}

לצורך אימות

תצורת דומיינים משמשת לקביעת אילו אתרים יכולים לארח את הווידג'ט של FastComments עבור החשבון שלך. זוהי צורה בסיסית של אימות, כלומר הוספה או הסרה של תצורות דומיין עלולה להשפיע על זמינות התקנת FastComments שלך בסביבת הייצור.

אל תסירו או תעדכנו את המאפיין domain של Domain Config עבור דומיין שנמצא בשימוש כרגע אלא אם המטרה היא לנטרל את הדומיין.

זה מתנהג באותו אופן כמו הסרת דומיין מ-/auth/my-account/configure-domains.

שימו לב שגם הסרה של דומיין מ-My Domains UI תסיר כל תצורה מקבילה עבור אותו דומיין שעשויה להיות נוספה דרך ממשק זה.

להתאמה אישית של אימיילים

קישור ההסרה בכותרת התחתונה של המייל, ותכונת 'הסרה בלחיצה אחת' שמוצעת על ידי לקוחות דוא״ל רבים, ניתנים להגדרה דרך ה-API הזה על ידי הגדרת footerUnsubscribeURL ו-emailHeaders, בהתאמה.

לגבי DKIM

לאחר שהגדרתם את רשומות ה-DNS של DKIM שלכם, פשוט עדכנו את DomainConfig עם תצורת DKIM שלכם באמצעות המבנה המוגדר.

GET /api/v1/domain-configs

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

API זה מספק את היכולת לאחזר את כל אובייקטי DomainConfig עבור שוכר.

דוגמת cURL ל-GET קונפיגורציית דומיין

Copy

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

מבנה בקשת GET קונפיגורציית דומיין

Copy

interface GetDomainConfigsRequestQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת GET קונפיגורציית דומיין

Copy

interface GetDomainConfigsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    /** The configurations! **/
    configurations: DomainConfig[] | null
}

GET /api/v1/domain-configs/:domain

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

ניתן לאחזר DomainConfigs בודדים לפי ה-domain התואם שלהם.

דוגמת cURL לקונפיגורציית דומיין לפי דומיין

Copy

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

מבנה בקשת קונפיגורציית דומיין לפי דומיין

Copy

interface DomainConfigsByDomainRequestQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת קונפיגורציית דומיין לפי דומיין

Copy

interface DomainConfigResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    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'
    /** Included on failure. **/
    reason?: string
    configuration?: DomainConfig | null
}

POST /api/v1/domain-configs

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

נקודת קצה API זו מספקת את היכולת ליצור קונפיגורציות דומיין.

הוספת קונפיגורציה לדומיין מאשרת את הדומיין הזה עבור חשבון FastComments.

מקרי שימוש נפוצים של API זה הם הגדרה ראשונית, אם רוצים להוסיף דומיינים רבים, או קונפיגורציה מותאמת אישית לשליחת אימיילים.

דוגמת cURL ל-POST קונפיגורציית דומיין

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/domain-configs?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "domain": "example.com",
    "emailFromName": "some from name",
    "emailFromEmail": "some@test.com",
    "logoSrc": "https://example.com/my-logo-big.png",
    "logoSrc100px": "https://example.com/my-logo-100px.png",
    "footerUnsubscribeURL": "http://example.com/unsubscribe-ui",
    "emailHeaders": {
        "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
        "List-Unsubscribe": "<https://example.com/opt-out/[userId]>"
    }
}'

מבנה בקשת POST קונפיגורציית דומיין

Copy

interface DomainConfigPostQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת POST קונפיגורציית דומיין

Copy

interface DomainConfigPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    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';
    /** Included on failure. **/
    reason?: string
    /** The created configuration. **/
    configuration?: DomainConfig
}

PATCH /api/v1/domain-configs/:domain

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

נקודת קצה API זו מספקת את היכולת לעדכן קונפיגורציית דומיין על ידי ציון רק הדומיין והמאפיין לעדכון.

דוגמת cURL ל-PATCH של DomainConfig

Copy

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

מבנה בקשת PATCH של DomainConfig

Copy

interface DomainConfigPatchQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת PATCH של DomainConfig

Copy

interface DomainConfigPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    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';
    /** Included on failure. **/
    reason?: string
    /** The updated configuration. **/
    configuration?: DomainConfig
}

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

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

נקודת קצה API זו מספקת את היכולת להחליף קונפיגורציית דומיין.

דוגמת cURL ל-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]>"
    }
}'

מבנה בקשת PUT קונפיגורציית דומיין

Copy

interface DomainConfigPutQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת PUT קונפיגורציית דומיין

Copy

interface DomainConfigPutResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    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';
    /** Included on failure. **/
    reason?: string
    /** The updated configuration. **/
    configuration?: DomainConfig
}

DELETE /api/v1/domain-configs/:domain

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

נתיב זה מספק הסרה של DomainConfig יחיד לפי מזהה.

הערה: הסרת DomainConfig תבטל את ההרשאה של אותו דומיין להשתמש ב-FastComments.
הערה: הוספה מחדש של דומיין דרך ממשק המשתמש תיצור מחדש את האובייקט (עם רק domain מאוכלס).

דוגמת cURL להסרת DomainConfig

Copy

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

מבנה בקשת הסרת DomainConfig

Copy

interface DomainConfigRequestQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת הסרת DomainConfig

Copy

interface DomainConfigDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-domain' | 'domain-config-does-not-exist'
    /** Included on failure. **/
    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
    /** READONLY - incremented for each new response. **/
    usedCount: number
    /** A date string for when the configuration was last used (result left). **/
    lastUsed?: string
    type: QuestionConfigType
    numStars?: number
    min?: number
    max?: number
    defaultValue?: number
    labelNegative?: string
    labelPositive?: string
    subQuestionIds?: string[]
    alwaysShowSubQuestions?: boolean
    reportingOrder: number
}

GET /api/v1/question-configs

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

נתיב זה מחזיר עד 100 אובייקטי QuestionConfig בכל פעם, מעומדים. העלות היא 1 לכל 100 אובייקטים. הם ממוינים לפי טקסט השאלה בסדר עולה (שדה question).

דוגמת QuestionConfig

Copy

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

מבנה בקשת QuestionConfig

Copy

interface QuestionConfigRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
    /** For pagination. Starts at 0. **/
    skip?: number
}

מבנה תגובת QuestionConfig

Copy

interface QuestionConfigByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    questionConfigs: QuestionConfig[]
}

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

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

נתיב זה מחזיר QuestionConfig יחיד לפי המזהה שלו.

דוגמת cURL ל-QuestionConfig לפי מזהה

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'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
    questionConfig?: QuestionConfig
}

POST /api/v1/question-configs

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

נקודת קצה API זו מספקת את היכולת ליצור QuestionConfig.

דוגמת cURL ל-POST QuestionConfig

Copy

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

מבנה בקשת POST QuestionConfig

Copy

interface QuestionConfigPostQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת POST QuestionConfig

Copy

interface QuestionConfigPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input';
    /** Included on failure. **/
    reason?: string
    /** The created object. **/
    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
    /** Beware! Changing type may throw off reporting if min/max is different. **/
    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'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'unauthorized' | 'missing-api-key' | 'missing-id' | 'not-found' | 'empty-request' | 'invalid-input'
    /** Included on failure. **/
    reason?: string
}

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

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

נתיב זה מספק הסרה של QuestionConfig לפי מזהה.

זה ימחק את כל תוצאות השאלות המתאימות (אך לא את התגובות). זה חלק מעלות הקרדיטים הגבוהה.

דוגמת 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'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
}

מבנה תוצאת שאלה

כדי לשמור תוצאות לשאלות, אתה יוצר 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
    /** For pagination. Starts at 0. **/
    skip?: number
    /** For pagination. **/
    limit?: number
    /** Get the results from a specific page. **/
    urlId?: string
    /** Get the results from a specific user. **/
    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 יחיד לפי המזהה שלו.

דוגמת cURL ל-QuestionResult לפי מזהה

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'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
    questionResult?: QuestionResult
}

POST /api/v1/question-results

Resource: QuestionResult as POST /api/v1/question-results Credit Cost: 1

נקודת קצה API זו מספקת את היכולת ליצור QuestionResult.

דוגמת cURL ל-POST QuestionResult

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/question-results?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "urlId": "some-page-id",
    "anonUserId": 'anon-0',
    "userId": 'user-0',
    "value": 10,
    "questionId": "some-question-id",
    "meta": [
        {
            name: "example",
            values: ["value-1", "value-2"]
        }
    ]
}'

מבנה בקשת POST QuestionResult

Copy

interface QuestionResultPostQueryParams {
    tenantId: string
    API_KEY: string
}

מבנה תגובת POST QuestionResult

Copy

interface QuestionResultPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input';
    /** Included on failure. **/
    reason?: string
    /** The created object. **/
    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'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'unauthorized' | 'missing-api-key' | 'missing-id' | 'not-found' | 'empty-request' | 'invalid-input'
    /** Included on failure. **/
    reason?: string
}

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

Resource: QuestionResult as DELETE /api/v1/question-results/:id Credit Cost: 1

נתיב זה מספק הסרה של QuestionResult לפי מזהה.

דוגמת 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'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
}

GET /api/v1/question-results-aggregate

Resource: QuestionResultsAggregate as GET /api/v1/question-results-aggregate Credit Cost: 2

כאן מתרחש איגום התוצאות.

מבנה תגובת האיגום הוא כדלקמן:

מבנה QuestionResultsAggregationResult

Copy

interface QuestionResultDataPoint {
    /** A map of value to count of occurrences of that value for the current data point (date bucket or page). **/
    v: Map<ValueAsString, number>
    total: number
}
interface QuestionResultsAggregationResult {
    /** Note - is null when timeBucket not specified. **/
    dataByDateBucket?: Map<DateString, QuestionResultDataPoint>
    dataByUrlId?: Map<URLIdString, QuestionResultDataPoint>
    countsByValue?: Map<ValueAsString, number>
    /** The total number of results aggregated. **/
    total: number
    /** The resulting weighted average. It is a float, usually two decimals or fewer. **/
    average: number
    /** A date string representing when this data was calculated, since it might come from cache. **/
    createdAt: string
}

הנה פרמטרי השאילתה הזמינים לאיגום:

מבנה בקשת QuestionResultsAggregation

Copy

interface QuestionResultsAggregateRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** You can aggregate results for one or more questions. **/
    questionId: string | string[]
    startDate?: string | number
    timeBucket?: 'day' | 'month' | 'year'
    /** Aggregate for a specific page. **/
    urlId?: string
    /** Aggregate for a specific user. **/
    userId?: string
    /** Force recalculate now and update the cache. **/
    forceRecalculate?: boolean
}

הנה דוגמת בקשה:

דוגמת QuestionResultsAggregation

Copy

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

דוגמת תגובה:

דוגמת תגובת QuestionResultsAggregation

Copy

    {
        "average": 8.33,
        "countsByValue": {
            "5": 1,
            "10": 2
        },
        "createdAt": "2023-08-30T00:00:00.000Z",
        "dataByUrlId": {
            "some-page": {
                "total": 3,
                "v": {
                    "5": 1,
                    "10": 2
                }
            }
        },
        "total": 3
    }

מבנה תגובת QuestionResultsAggregation

Copy

interface QuestionResultsAggregationResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    data: QuestionResultsAggregationResult
}

הערות ביצועים

עבור החטאת מטמון, איגומים בדרך כלל לוקחים חמש שניות למיליון תוצאות.
אחרת, הבקשות הן בזמן קבוע.

הערות על מטמון ועלות

כאשר forceRecalculate מצוין, העלות היא תמיד 10, במקום 2 הרגיל.
אם המטמון פג ונתונים מחושבים מחדש, העלות היא עדיין 2 קבוע אם forceRecalculate לא מצוין. המטמון פג על בסיס גודל מערך הנתונים המאוגד (יכול לנוע בין 30 שניות ל-5 דקות).
זה כדי לתמרץ שימוש במטמון.

GET /api/v1/question-results-aggregate/combine/comments

Resource: QuestionResultsCombinedWithComments as GET /api/v1/question-results-aggregate/combine/comments Credit Cost: 2

כאן מתרחש שילוב תוצאות עם תגובות. שימושי ליצירת תרשים "תגובות חיוביות ושליליות אחרונות" למוצר, לדוגמה.

אתה יכול לחפש באמצעות טווח ערכים (כולל), שאלה אחת או יותר, ולפי תאריך התחלה (כולל).

מבנה התגובה הוא כדלקמן:

מבנה QuestionResultsCombinedWithCommentsResponse

Copy

interface SimpleComment {
    id: string
    commenterName: string
    userId?: string
    date: string
    commentHTML: string
}
interface SimpleQuestionResult {
    id: string
    value: number
}
interface CommentAndResult {
    comment: SimpleComment
    result: SimpleQuestionResult
}
interface QuestionResultsCombinedWithCommentsResponse {
    /** A date string representing when this data was calculated, since it might come from cache. **/
    createdAt: string
    results: CommentAndResult[]
}

הנה פרמטרי השאילתה הזמינים לאיגום:

מבנה בקשת QuestionResultsCombineComments

Copy

interface QuestionResultsAggregateRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** You can aggregate results for one or more questions. **/
    questionId: string | string[]
    startDate?: string | number
    urlId?: string
    minValue: number
    maxValue: number
    limit?: number
    forceRecalculate?: boolean
}

הנה דוגמת בקשה:

דוגמת QuestionResultsCombineComments

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/question-results-aggregation/combine/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&questionId=some-question-id&minValue=5&maxValue=10'

דוגמת תגובה:

דוגמת תגובת QuestionResultsCombineComments

Copy

{
    "createdAt": "2023-08-30T00:00:00.000Z",
    "results": [
        {
            "comment": {
                "id": "some-id",
                "commentHTML": "test-2",
                "commenterName": "Test",
                "date": "2023-08-30T00:00:00.000Z",
                "userId": "some-user-id"
            },
            "result": {
                "id": "some-id",
                "value": 10
            }
        },
        {
            "comment": {
                "id": "some-id",
                "commentHTML": "test-0",
                "commenterName": "Some Name",
                "date": "2023-08-30T00:00:00.000Z",
                "userId": "some-user-id"
            },
            "result": {
                "id": "some-id",
                "value": 5
            }
        }
    ]
}

מבנה תגובת QuestionResultsCombineComments

Copy

interface QuestionResultsCombineCommentsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    data: QuestionResultsCombinedWithCommentsResponse
}

הערות על מטמון ועלות

כאשר forceRecalculate מצוין, העלות היא תמיד 10, במקום 2 הרגיל.
אם המטמון פג ונתונים מחושבים מחדש, העלות היא עדיין 2 קבוע אם forceRecalculate לא מצוין.
זה כדי לתמרץ שימוש במטמון.

מבנה תג משתמש

UserBadge הוא אובייקט שמייצג תג שמוקצה למשתמש במערכת FastComments.

תגים יכולים להיות מוקצים למשתמשים באופן אוטומטי על בסיס הפעילות שלהם (כגון מספר תגובות, זמן תגובה, סטטוס וותק) או באופן ידני על ידי מנהלי האתר.

המבנה של האובייקט UserBadge הוא כדלקמן:

מבנה UserBadge

Copy

export interface UserBadge {
    /** מזהה ייחודי להקצאת תג המשתמש הזו */
    id: string
    /** ID of the user this badge is assigned to */
    userId: string
    /** ID of the badge definition from the tenant's badge catalog */
    badgeId: string
    /** ID of the tenant that created/assigned this badge */
    fromTenantId: string
    /** When this badge was created (milliseconds since epoch) */
    createdAt?: number
    /** When this badge was received by the user (milliseconds since epoch) */
    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
    /** For threshold-based badges, the threshold value */
    threshold?: number
    /** The name/label of the badge */
    name?: string
    /** Detailed description of the badge */
    description?: string
    /** The text shown on the badge */
    displayLabel?: string
    /** URL to an image shown on the badge */
    displaySrc?: string
    /** Background color for the badge (hex code) */
    backgroundColor?: string
    /** Border color for the badge (hex code) */
    borderColor?: string
    /** Text color for the badge (hex code) */
    textColor?: string
    /** Additional CSS class for styling */
    cssClass?: string
    /** For veteran badges, the time threshold in milliseconds */
    veteranUserThresholdMillis?: number
    /** Whether this badge is displayed on the user's comments */
    displayedOnComments: boolean
    /** The display order of the badge */
    order?: number
    /** If set, this badge is only displayed on the page with the matching urlId. Null for global badges. */
    urlId?: string | null
}

---

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

נקודת קצה זו מאפשרת לך לאחזר תג משתמש ספציפי לפי המזהה הייחודי שלו.

דוגמת בקשה:

דוגמת בקשת GET

Copy

Run

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

דוגמת תגובה:

תגובה

Copy

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

תגובות שגיאה אפשריות:

שגיאה: מזהה שוכר חסר

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

תגובות שגיאה אפשריות:

שגיאה: מזהה שוכר חסר

Copy

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

שגיאה: מזהה משתמש חסר

Copy

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

שגיאה: מזהה תג חסר

Copy

{
  "status": "failed",
  "code": "missing-badge-id",
  "reason": "Badge ID (body param: badgeId) is required."
}

שגיאה: תג לא נמצא

Copy

{
  "status": "failed",
  "code": "badge-not-found",
  "reason": "The badge badgeDef789 was not found or is not enabled."
}

שגיאה: משתמש לא מורשה

Copy

{
  "status": "failed",
  "code": "unauthorized-user",
  "reason": "You can only add badges to users who belong to your tenant or have commented on your site."
}

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

נקודת קצה זו מאפשרת לך לעדכן הקצאת תג משתמש.

כרגע, המאפיין היחיד שניתן לעדכן הוא displayedOnComments, השולט האם התג מוצג בתגובות המשתמש.

דוגמת בקשה:

דוגמת בקשת 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
}'

דוגמת תגובה:

תגובה

Copy

{
  "status": "success"
}

תגובות שגיאה אפשריות:

שגיאה: מזהה שוכר חסר

Copy

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

שגיאה: מזהה חסר

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

תגובות שגיאה אפשריות:

שגיאה: מזהה שוכר חסר

Copy

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

שגיאה: מזהה חסר

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 {
    /** Unique identifier for this progress record */
    id: string
    /** ID of the tenant this progress record belongs to */
    tenantId: string
    /** ID of the user this progress record tracks */
    userId: string
    /** ID of the user's first comment in the system */
    firstCommentId?: string
    /** Date of the user's first comment (milliseconds since epoch) */
    firstCommentDate?: number
    /** Automatically calculated trust factor based on user activity */
    autoTrustFactor?: number
    /** Manually set trust factor by administrators */
    manualTrustFactor?: number
    /** Detailed progress object with various metrics, keys match BadgeType enum */
    progress: {
        /** 0: CommentCount - Count of comments the user has made */
        '0'?: number
        /** 1: CommentUpVotes - Count of upvotes the user has received */
        '1'?: number
        /** 2: CommentReplies - Count of replies the user has made */
        '2'?: number
        /** 3: CommentsPinned - Count of pinned comments the user has */
        '3'?: number
        /** 4: Veteran - User's account age */
        '4'?: number
        /** 5: NightOwl - Times user has posted during nighttime hours */
        '5'?: number
        /** 6: FastReplyTime - Average reply time in milliseconds */
        '6'?: number
        /** 7: ModeratorCommentsDeleted - For moderator badges, comments deleted count */
        '7'?: number
        /** 8: ModeratorCommentsApproved - For moderator badges, comments approved count */
        '8'?: number
        /** 9: ModeratorCommentsUnapproved - For moderator badges, comments unapproved count */
        '9'?: number
        /** 10: ModeratorCommentsReviewed - For moderator badges, comments reviewed count */
        '10'?: number
        /** 11: ModeratorCommentsMarkedSpam - For moderator badges, comments marked as spam count */
        '11'?: number
        /** 12: ModeratorCommentsMarkedNotSpam - For moderator badges, comments marked as not spam count */
        '12'?: number
        /** 13: RepliedToSpecificPage - For each page, count of replies */
        '13'?: Record<string, number>
    }
}

GET /api/v1/user-badge-progress

נקודת קצה זו מאפשרת לך לשלוף רשומות של התקדמות תגי משתמש בהתבסס על קריטריונים שונים.

Example Request:

רשימת התקדמות תג - דוגמת GET

Copy

Run

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

ניתן להוסיף פרמטרי שאילתה שונים כדי לסנן את התוצאות:

userId - קבל התקדמות עבור משתמש ספציפי
limit - מספר מקסימלי של רשומות להחזרה (ברירת מחדל 30, מקסימום 200)
skip - מספר רשומות לדלג (לעימוד)

Example Response:

תגובה

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

Possible Error Responses:

שגיאה: מזהה השוכר חסר

Copy

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

שגיאה: ערך limit לא תקין

Copy

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

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

נקודת קצה זו מאפשרת לך לאחזר רשומת התקדמות תג משתמש ספציפית לפי המזהה הייחודי שלה.

דוגמת בקשה:

דוגמת בקשת GET

Copy

Run

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

דוגמת תגובה:

תגובה

Copy

{
  "status": "success",
  "userBadgeProgress": {
    "id": "progress123",
    "tenantId": "tenant001",
    "userId": "user456",
    "firstCommentId": "comment789",
    "firstCommentDate": 1650532511000,
    "autoTrustFactor": 0.75,
    "progress": {
      "0": 42,
      "1": 120,
      "2": 15,
      "3": 3,
      "5": 5,
      "6": 1800000,
      "8": 0,
      "7": 0
    }
  }
}

תגובות שגיאה אפשריות:

שגיאה: מזהה שוכר חסר

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

נקודת קצה זו מאפשרת לך לאחזר רשומת התקדמות תג של משתמש לפי מזהה המשתמש שלו.

דוגמת בקשה:

דוגמת בקשת GET

Copy

Run

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

דוגמת תגובה:

תגובה

Copy

{
  "status": "success",
  "userBadgeProgress": {
    "id": "progress123",
    "tenantId": "tenant001",
    "userId": "user456",
    "firstCommentId": "comment789",
    "firstCommentDate": 1650532511000,
    "autoTrustFactor": 0.75,
    "progress": {
      "0": 42,
      "1": 120,
      "2": 15,
      "3": 3,
      "5": 5,
      "6": 1800000,
      "8": 0,
      "7": 0
    }
  }
}

תגובות שגיאה אפשריות:

שגיאה: מזהה שוכר חסר

Copy

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

שגיאה: מזהה משתמש חסר

Copy

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

שגיאה: לא נמצא

Copy

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

לסיכום

אנו מקווים שמצאתם את תיעוד ה-API שלנו מקיף וקל להבנה. אם מצאתם פערים, אנא עדכנו אותנו למטה.

שפה 🇮🇱 עברית

משאבי API

אגרגציות

יומני ביקורת

תגובות

תבניות דוא״ל

תגיות

מודרטורים

ספירת התראות

התראות

עמודים

אירועי Webhook ממתינים

משתמשי SSO

מנויים

שימוש יומי של שוכר

שוכרים

חבילות שוכר

משתמשי שוכר

משתמשים

הצבעות

הגדרות דומיין

הגדרות שאלה

תוצאות שאלות

אגרגציית תוצאות שאלות

תגי משתמש

התקדמות תגי משתמש

ממשק ה-API של FastComments

SDKs שנוצרו

אימות

הערת אבטחה

אפשרות אימות אחת - כותרות

אפשרות אימות שנייה - פרמטרי שאילתה

קריאה של הכתיבות שלך

משאבי API

שימוש במשאבים

הערה!

לאגד את הנתונים שלך

דוגמאות

דוגמה: ספירת ייחודיים

דוגמה: ספירת נבדלים

דוגמה: סיכום ערכים של שדות מרובים

דוגמה: ממוצע ערכים של שדות מרובים

דוגמה: ערכי מינימום/מקסימום של שדות מרובים

דוגמה: ספירת ערכים ייחודיים של שדות מרובים

דוגמה: יצירת שאילתה

דוגמה: ספירת תגובות הממתינות לבדיקה

דוגמה: פירוט תגובות מאושרות, נבדקות וספאם

מבנים

מבנה יומן ביקורת

GET /api/v1/audit-logs

מבנה תגובה

Comment Text Structure

Tagging

HashTags

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