API | FastComments Docs

FastComments API

FastComments는 여러 리소스와 상호 작용하기 위한 API를 제공합니다. 우리 플랫폼과 통합을 구축하거나, 직접 클라이언트를 만들어 보세요!

이 문서에서는 API가 지원하는 모든 리소스가 요청 및 응답 타입과 함께 문서화되어 있습니다.

엔터프라이즈 고객의 경우 모든 API 접근이 감사 로그에 기록됩니다.

생성된 SDKs

FastComments는 이제 코드에서 API Spec을 생성합니다 (아직 완전하지는 않지만 많은 API가 포함되어 있습니다).

또한 인기 있는 언어용 SDK도 제공됩니다:

인증

API는 api key를 X-API-KEY 헤더 또는 API_KEY 쿼리 매개변수로 전달하여 인증합니다. API 호출을 위해 tenantId도 필요합니다. 이는 api key가 있는 동일한 페이지에서 가져올 수 있습니다.

보안 참고

이 경로들은 서버에서 호출되도록 되어 있습니다. 브라우저에서 절대 호출하지 마세요. 이렇게 하면 API 키가 노출됩니다 - 페이지의 소스 코드를 볼 수 있는 누구에게나 계정에 대한 전체 접근 권한이 부여됩니다!

인증 옵션 1 - 헤더

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

인증 옵션 2 - 쿼리 매개변수

Query Param: API_KEY
Query Param: tenantId

API 리소스

리소스 사용량

API에서 데이터를 가져오는 것은 귀하의 계정 사용량으로 집계된다는 점을 유의해야 합니다.

각 리소스는 해당 사용량을 자체 섹션에 나열합니다.

일부 리소스는 다른 리소스보다 제공 비용이 더 높습니다. 각 엔드포인트는 API 호출당 고정된 크레딧 비용을 가집니다. 일부 엔드포인트의 경우 옵션 및 응답 크기에 따라 필요한 크레딧 수가 달라집니다.

API 사용량은 청구 분석 페이지에서 확인할 수 있으며, 몇 분마다 업데이트됩니다.

참고!

혼란을 줄이기 위해 urlId에 전달할 값을 결정할 때 먼저 Pages 문서를 읽어보시길 권장합니다.

데이터 집계

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

이 API는 문서를 그룹화(groupBy가 제공된 경우)하고 여러 연산을 적용하여 집계합니다. 다양한 연산(예: sum, countDistinct, avg 등)을 지원합니다.

비용은 가변적입니다. 스캔된 객체 500개마다 API 크레딧 1개가 소모됩니다.

기본적으로 각 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 }
}

구조

Aggregate 요청 구조

Copy

export type AggregationOpType = 'sum' | 'countDistinct' | 'distinct' | 'avg' | 'min' | 'max' | 'count';
/** 필드에 적용될 연산 */
export interface AggregationOperation {
    /** 연산을 적용할 필드 */
    field: string;
    /** 연산의 종류 */
    op: AggregationOpType;
    /** 출력에 대한 선택적 별칭; 제공되지 않으면 기본 별칭이 계산됩니다 */
    alias?: string;
    expandArray?: boolean;
}
export interface QueryPredicate {
    key: string
    value: string | number | boolean
    operator: 'eq' | 'not_eq' | 'greater_than' | 'less_than' | 'contains'
}
export interface AggregationRequest {
    query?: QueryPredicate[];
    resourceName: string;
    groupBy?: string[];
    operations: AggregationOperation[];
    sort?: {
        field: string;
        dir: 'asc' | 'desc';
    };
}
type DistinctAccumulator = Record<string, number>;
type GroupValues = Record<string, string>;
export type AggregationValue = {
    distinctCounts?: DistinctAccumulator
    distinctCount?: number
    numericValue?: number
    stringValue?: string
    groups?: GroupValues
};

Aggregate 응답 구조

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를 통해 감사 로그를 읽을 수 있습니다.

이 감사 로그의 이벤트는 2년 후에 만료됩니다.

GET /api/v1/audit-logs

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

이 API는 skip, before, after 매개변수로 제공되는 페이지네이션을 사용합니다. AuditLogs는 when과 id로 정렬되며 한 페이지당 1000개가 반환됩니다.

매 1000개의 로그를 가져오는 데는 크레딧 10이 소모됩니다.

기본적으로, 가장 최신 항목이 먼저인 목록을 받습니다. 이렇게 하면 skip=0부터 폴링을 시작하여 마지막으로 처리한 레코드를 찾을 때까지 페이지네이션할 수 있습니다.

또는 오래된 항목부터 정렬하여 더 이상 레코드가 없을 때까지 페이지네이션할 수 있습니다.

정렬은 order를 ASC 또는 DESC로 설정하여 수행할 수 있습니다. 기본값은 ASC입니다.

날짜로 쿼리하는 것은 밀리초 단위 타임스탬프로 before와 after를 사용하는 방식으로 가능합니다. before와 after는 포함되지 않습니다.

AuditLog cURL 예제

Copy

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

AuditLog 요청 구조

Copy

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

AuditLog 응답 구조

Copy

interface CommentsResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** 실패 시 포함됩니다. **/
    reason?: string
    /** 로그들! **/
    auditLogs: AuditLog[]
}

댓글 구조

A Comment 객체는 사용자가 남긴 댓글을 나타냅니다.

상위 및 하위 댓글 간의 관계는 parentId를 통해 정의됩니다.

Comment 객체의 구조는 다음과 같습니다:

댓글 구조

Copy

interface Comment {
    /** 읽기 전용: 스팸 엔진이 해당 댓글을 스팸으로 판별한 경우 true로 설정됩니다. **/
    aiDeterminedSpam?: boolean
    /** 댓글이 표시되도록 승인되었는지 여부. 댓글 저장 시 true로 설정되며, 그렇지 않으면 숨겨집니다. **/
    approved?: boolean
    /** 사용자의 아바타. **/
    avatarSrc?: string
    /** 자식 댓글. 모든 시나리오에서 채워지지는 않습니다. API를 통해 asTree가 true로 설정된 경우 사용됩니다. **/
    children: Comment[]
    /** 작성자가 입력한 원본 댓글 텍스트. **/
    comment: string
    /** 읽기 전용: 작성자의 댓글을 파싱해 HTML로 변환한 값. **/
    commentHTML?: string
    /** 작성자의 이메일. 익명 댓글이 꺼져 있으면 필요합니다. **/
    commenterEmail?: string
    /** 작성자의 링크(예: 블로그). **/
    commenterLink?: string
    /** 작성자의 이름. 항상 필요합니다. 사용할 수 없다면 "Anonymous" 같은 값으로 설정하세요. **/
    commenterName: string
    /** 댓글이 작성된 날짜(UTC epoch). **/
    date: number
    /** 댓글의 "표시 레이블" - 예: "Admin", "Moderator" 또는 "VIP User" 같은 값. **/
    displayLabel?: string
    /** 댓글이 게시된 도메인. **/
    domain?: string
    /** 읽기 전용: 댓글이 신고된 횟수. **/
    flagCount?: number
    /** 댓글에 작성되어 성공적으로 파싱된 #해시태그들. 쿼리를 위해 해시태그를 수동으로 추가할 수도 있지만, 그러면 댓글 텍스트에 자동으로 표시되지는 않습니다. **/
    hashTags?: CommentHashTag[]
    /** 읽기 전용: 댓글에 이미지가 포함되어 있는지 여부. **/
    hasImages?: boolean
    /** 읽기 전용: 댓글에 링크가 포함되어 있는지 여부. **/
    hasLinks?: boolean
    /** 읽기 전용: 고유 댓글 ID. **/
    id: string
    /** 생성 시에만! 저장을 위해 해시됩니다. **/
    ip?: string
    /** 읽기 전용: 현재 사용자가 이 댓글 작성자를 차단했는지 여부. **/
    isBlocked?: boolean
    /** 읽기 전용: 댓글 작성자가 관리자인지 여부. userId를 기반으로 자동 설정됩니다. **/
    isByAdmin?: boolean
    /** 읽기 전용: 댓글 작성자가 중재자인지 여부. userId를 기반으로 자동 설정됩니다. **/
    isByModerator?: boolean
    /** 댓글이 소프트 삭제된 경우(true로 설정됩니다). (다른 구성 때문에 플레이스홀더를 남겨야 하는 경우) **/
    isDeleted?: boolean
    /** 사용자의 계정이 삭제되어 댓글만 보존해야 하는 경우 true로 설정됩니다. **/
    isDeletedUser?: boolean
    /** 읽기 전용: 현재 로그인한 사용자(contextUserId)가 이 댓글을 신고했는지 여부. **/
    isFlagged?: boolean
    /** 댓글이 고정되어 있는지 여부. **/
    isPinned?: boolean
    /** 새 답글 작성이 잠겨 있는지 여부(중재자는 여전히 답글 작성 가능). **/
    isLocked?: boolean
    /** 댓글이 스팸인지 여부. **/
    isSpam?: boolean
    /** 읽기 전용: 현재 사용자(contextUserId)가 이 댓글에 대해 downvote했는지 여부. **/
    isVotedDown?: boolean
    /** 읽기 전용: 현재 사용자(contextUserId)가 이 댓글에 대해 upvote했는지 여부. **/
    isVotedUp?: boolean
    /** 댓글의 로케일. 제공되지 않으면 HTTP Accept-Language 헤더에서 파생됩니다. **/
    locale?: 'de_de' | 'en_us' | 'es_es' | 'fr_fr' | 'it_it' | 'ja_jp' | 'ko_kr' | 'pl_pl' | 'pt_br' | 'ru_ru' | 'tr_tr' | 'zh_cn' | 'zh_tw'
    /** 읽기 전용: 댓글에서 성공적으로 파싱된 @멘션들. **/
    mentions?: CommentUserMention[]
    /** 댓글에 연결된 선택적 메타데이터. **/
    meta?: Record<string, string | number | boolean>
    /** 이 댓글에 연결된 선택적 중재 그룹 ID 목록. **/
    moderationGroupIds?: string[]|null
    /** 읽기 전용: 현재 사용자(contextUserId)가 이 댓글에 남긴 투표에 해당하는 투표 객체의 ID. **/
    myVoteId?: string
    /** 이 댓글에 대해 작성자들에게 알림이 전송되었는지 여부. 가져오기(imports) 시 알림 전송을 방지하려면 이 값을 true로 설정하세요. **/
    notificationSentForParent?: boolean
    /** 이 댓글에 대해 테넌트 사용자들에게 알림이 전송되었는지 여부. 가져오기 시 알림 전송을 방지하려면 이 값을 true로 설정하세요. **/
    notificationSentForParentTenant?: boolean
    /** 이 댓글이 작성된 페이지의 제목. **/
    pageTitle?: string
    /** 댓글에 답글을 다는 경우, 답글 대상 댓글의 ID입니다. **/
    parentId?: string|null
    /** 댓글이 검토됨으로 표시되었는지 여부. **/
    reviewed: boolean
    /** 댓글이 속한 테넌트 ID. **/
    tenantId: string
    /** 댓글을 작성한 사용자. 이름/이메일로 댓글을 저장하면 자동으로 생성됩니다. **/
    userId?: string|null
    /** 이 댓글이 표시되는 위치의 URL(예: 블로그 게시물). **/
    url: string
    /** 전달한 urlId의 "정리된" 버전. 저장 시에는 이 필드를 지정하지만, 댓글을 가져올 때 이 값은 정리되어 원래 값은 "urlIdRaw"로 이동합니다. **/
    urlId: string
    /** 읽기 전용: 전달한 원래 urlId. **/
    urlIdRaw?: string
    /** 사용자와 이 댓글이 인증되었는지 여부. **/
    verified: boolean
    /** 찬성(업) 투표 수. **/
    votesUp?: number
    /** 반대(다운) 투표 수. **/
    votesDown?: number
    /** 댓글의 "카르마"(= 찬성 수 - 반대 수). **/
    votes?: number
}

일부 필드는 READONLY로 표시되어 있습니다 — 이들 필드는 API에서 반환되지만 설정할 수 없습니다.

댓글 텍스트 구조

댓글은 FastComments 변형 마크다운으로 작성됩니다. 이는 일반 마크다운에 전통적인 bbcode 스타일의 이미지 태그(예: [img]path[/img])를 추가한 것입니다.

텍스트는 두 필드에 저장됩니다. 사용자가 입력한 원문 텍스트는 comment 필드에 변경 없이 저장됩니다. 이 텍스트는 렌더링되어 commentHTML 필드에 저장됩니다.

허용되는 HTML 태그는 b, u, i, strike, pre, span, code, img, a, strong, ul, ol, li, and br입니다.

허용되는 HTML이 매우 적은 하위 집합이므로 HTML을 렌더링하는 것이 권장됩니다. 렌더러를 만드는 것은 비교적 간단합니다. 예를 들어 React Native와 Flutter용 라이브러리가 여러 개 있습니다.

정규화되지 않은 comment 필드의 값을 렌더링하도록 선택할 수도 있습니다. 예제 파서가 여기 있습니다..

예제 파서는 HTML과 함께 작동하도록 조정할 수 있으며, HTML 태그를 플랫폼에서 렌더링할 예상 요소로 변환할 수 있습니다.

태깅

댓글에서 사용자가 태그되면 해당 정보는 mentions라는 리스트에 저장됩니다. 해당 리스트의 각 객체는 다음 구조를 가집니다.

댓글 멘션 객체

Copy

Run

interface CommentUserMention {
    /** 사용자 ID. SSO 사용자의 경우 테넌트 ID가 접두사로 붙습니다. **/
    id: string
    /** 최종 @멘션 태그 텍스트(@ 기호 포함). **/
    tag: string
    /** 원래의 @멘션 태그 텍스트(@ 기호 포함). **/
    rawTag: string
    /** 태그된 사용자의 유형. user = FastComments.com 계정, sso = SSO 사용자. **/
    type: 'user'|'sso'
    /** 사용자가 알림을 수신 거부하더라도 이 값은 여전히 true로 설정됩니다. **/
    sent: boolean
}

해시태그

해시태그가 사용되어 성공적으로 파싱되면 그 정보는 hashTags라는 리스트에 저장됩니다. 해당 리스트의 각 객체는 다음과 같은 구조를 가집니다. retain이 설정되어 있으면 해시태그를 쿼리를 위해 댓글의 hashTags 배열에 수동으로 추가할 수도 있습니다.

댓글 해시태그 객체

Copy

Run

interface CommentHashTag {
    /** 해시태그 ID. **/
    id: string
    /** 최종 #해시태그 텍스트(# 기호 포함). **/
    tag: string
    /** 해시태그에 맞춤 URL이 연결되어 있다면 이 값이 정의됩니다. **/
    url?: string
    /** 댓글이 업데이트될 때 댓글 텍스트에 존재하지 않더라도 해시태그를 유지(retain)해야 하는지 여부. 댓글 텍스트를 변경하지 않고 댓글에 태그를 추가할 때 유용합니다. **/
    retain?: boolean
}

GET /api/v1/comments

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

이 API는 사용자에게 표시할 댓글을 가져오는 데 사용됩니다. 예를 들어 승인되지 않았거나 스팸인 댓글은 자동으로 필터링됩니다.

페이지네이션

페이지네이션은 성능 요구사항과 사용 사례에 따라 두 가지 방법 중 하나로 수행할 수 있습니다:

가장 빠름: 사전 계산된 페이지네이션(Precalculated Pagination):
1. 이것이 FastComments가 우리 미리 제작된 위젯과 클라이언트를 사용할 때 작동하는 방식입니다.
2. "다음"을 클릭하면 단순히 페이지 수가 증가합니다.
3. 이를 키-값 저장소에서 검색되는 것으로 생각할 수 있습니다.
4. 이 방식에서는 page 파라미터를 0부터 정의하고 정렬 방향을 direction으로 지정하면 됩니다.
5. 페이지 크기는 커스터마이제이션 규칙을 통해 맞춤 설정할 수 있습니다.
가장 유연함: 유연한 페이지네이션(Flexible Pagination):
1. 이 방식에서는 사용자 정의 limit 및 skip 파라미터를 정의할 수 있습니다. page는 전달하지 마세요.
2. 정렬 direction도 지원됩니다.
3. limit은 skip이 적용된 후 반환할 전체 수입니다.
  - 예시: page size = 100이고 page = 2인 경우 skip = 200, limit = 100으로 설정합니다.
4. 자식 댓글도 여전히 페이지네이션에 포함됩니다. asTree 옵션을 사용하여 이를 회피할 수 있습니다.
  - limitChildren 및 skipChildren으로 자식들을 페이지네이션할 수 있습니다.
  - 반환되는 스레드의 깊이를 maxTreeDepth로 제한할 수 있습니다.

스레드

Precalculated Pagination을 사용할 때, 댓글은 페이지별로 그룹화되며 스레드의 댓글이 전체 페이지에 영향을 미칩니다.
1. 이 방식에서는 클라이언트가 parentId 기반으로 스레드를 결정할 수 있습니다.
2. 예를 들어, 한 개의 최상위 댓글과 29개의 답글이 있는 페이지에서 API에 page=0을 설정하면 최상위 댓글 하나와 29개의 자식만 받습니다.
3. 예시 이미지(여러 페이지를 설명).
Flexible Pagination을 사용할 때는 parentId 파라미터를 정의할 수 있습니다.
1. 최상위 댓글만 가져오려면 이것을 null로 설정하세요.
2. 그런 다음 스레드를 보려면 API를 다시 호출하고 parentId를 전달하세요.
3. 일반적인 해결책은 최상위 댓글에 대해 API 호출을 하고 각 댓글의 자식 댓글을 가져오기 위해 병렬 API 호출을 하는 것입니다.
NEW As of Feb 2023! &asTree=true를 사용하여 트리로 가져올 수 있습니다.
1. 이를 Flexible Pagination as a Tree로 생각할 수 있습니다.
2. 페이지네이션에는 최상위 댓글만 계산됩니다.
3. 트리를 루트에서 시작하려면 parentId=null로 설정하세요(반드시 parentId를 설정해야 합니다).
4. 페이지네이션을 위해 skip 및 limit을 설정하세요.
5. asTree를 true로 설정하세요.
6. 이 경우 백엔드가 더 많은 작업을 수행해야 하므로 크레딧 비용이 2x 증가합니다.
7. 필요에 따라 maxTreeDepth, limitChildren, skipChildren를 설정하세요.

트리 설명

asTree를 사용할 때 페이지네이션을 이해하기 어려울 수 있습니다. 다음은 유용한 그래픽입니다:

Tree Pagination Diagram

사용자 컨텍스트에서 댓글 가져오기

/comments API는 두 가지 컨텍스트에서 사용될 수 있으며 서로 다른 사용 사례에 적합합니다:

자체 클라이언트를 빌드하기 위해 정렬되고 태그된 정보를 반환하려는 경우.
- 이 경우 contextUserId 쿼리 파라미터를 정의하세요.
맞춤 통합을 위해 백엔드에서 댓글을 가져오는 경우.
- 플랫폼은 contextUserId 없이 기본적으로 이 모드를 사용합니다.

댓글 사전 계산 페이지네이션

Copy

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

댓글 유연 페이지네이션

Copy

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

사용자 컨텍스트에서의 댓글 유연 페이지네이션

Copy

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

최상위 댓글만을 위한 사용자 컨텍스트의 댓글 유연 페이지네이션

Copy

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

댓글을 트리로 가져오기

댓글을 트리로 반환받을 수 있으며, 페이지네이션은 최상위 댓글만 계산합니다.

사용자 컨텍스트에서의 트리형 댓글

Copy

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

최상위 댓글과 바로 아래 자식들만 받고 싶나요? 다음과 같이 할 수 있습니다:

최대 깊이의 트리형 댓글

Copy

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

그러나 UI에서 각 댓글에 "답글 보기" 버튼을 표시할지 여부를 알아야 할 수 있습니다. 트리로 댓글을 가져올 때는 해당 댓글에 적용 가능한 경우 hasChildren 속성이 태그로 붙습니다.

해시태그로 검색하여 트리형 댓글 가져오기

API를 사용하면 테넌트 전체(한 페이지나 urlId에 한정되지 않음)를 대상으로 해시태그로 검색할 수 있습니다.

이 예제에서는 urlId를 생략하고 여러 해시태그로 검색합니다. API는 요청된 모든 해시태그를 가진 댓글만 반환합니다.

해시태그로 검색한 사용자 컨텍스트의 트리형 댓글

Copy

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

모든 요청 파라미터

댓글 요청 구조

Copy

interface CommentsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** 댓글이 연결된 urlId(페이지 URL 또는 기사 ID). **/
    urlId?: string
    /** 이 사용자가 작성한 댓글로 반환을 제한합니다. **/
    userId?: string
    /** 해시태그로 검색할 때 사용합니다. 여러 해시태그의 교집합으로 좁히려면 &hashTag=a&hashTag=b 를 사용하세요. **/
    hashTag?: string
    /** 정렬 방향. 기본값은 MR(가장 관련성 높은 순). 다른 옵션으로는 OF(오래된 것부터) 및 NF(최신순)가 있습니다. **/
    direction?: 'MR' | 'OF' | 'NF'
    /** 사전 계산 페이지네이션: 가져올 페이지로, 0부터 시작합니다. 모든 댓글을 원하면 -1을 전달하세요(최대 250). **/
    page?: number
    /** 유연한 페이지네이션: 몇 개의 댓글을 반환할지 지정합니다. **/
    limit?: number
    /** 유연한 페이지네이션: 각 부모에 대해 몇 개의 자식 댓글을 반환할지 지정합니다. **/
    limitChildren?: number
    /** 유연한 페이지네이션: 몇 개의 댓글을 건너뛸지 지정합니다. **/
    skip?: number
    /** 유연한 페이지네이션: 각 부모에 대해 몇 개의 자식 댓글을 건너뛸지 지정합니다. **/
    skipChildren?: number
    /** 차단 및 신고된 댓글을 판단하기 위해 사용됩니다. **/
    contextUserId?: string
    /** 차단 및 신고된 댓글을 판단하기 위해 사용됩니다. **/
    anonUserId?: string
    /** 자식 댓글을 가져오기 위해 사용됩니다. **/
    parentId?: string
    /** 트리로 가져오기 위해 사용됩니다. **/
    asTree?: boolean
    /** 트리에서 얼마나 깊이 들어갈지 지정합니다. 0이면 자식을 반환하지 않습니다. 1이면 바로 아래 자식을 반환합니다. **/
    maxTreeDepth?: number
}

응답

댓글 응답 구조

Copy

interface CommentsResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'missing-date' | 'unauthorized-page' | 'invalid-pagination-request' | 'invalid-limit' | 'invalid-limit-children' | 'invalid-skip' | 'invalid-skip-children' | 'invalid-max-tree-depth'
    /** 실패 시 포함됩니다. **/
    reason?: string
    /** 댓글들입니다! **/
    comments: Comment[]
}

유용한 팁

URL ID

대부분의 경우 urlId 파라미터와 함께 Comment API를 사용하고 싶을 것입니다. 먼저 Pages API를 호출하여 사용 가능한 urlId 값이 어떻게 생겼는지 확인할 수 있습니다.

익명 액션

익명 댓글 기능을 위해서는 댓글을 가져올 때, 그리고 신고 및 차단을 수행할 때 anonUserId를 전달하는 것이 좋습니다.

(!) 많은 앱 스토어에서는 사용자가 로그인하지 않았더라도 자신이 볼 수 있는 사용자 생성 콘텐츠를 신고할 수 있어야 하기 때문에 이것이 요구됩니다. 이를 준수하지 않으면 해당 스토어에서 앱이 제거될 수 있습니다.

댓글이 반환되지 않는 경우

댓글이 승인되었는지, 스팸이 아닌지 확인하세요.

GET /api/v1/comments/:id

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

이 API는 id로 단일 댓글을 가져오는 기능을 제공합니다.

댓글 ID 조회 cURL 예제

Copy

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

댓글 ID 조회 요청 구조

Copy

interface CommentsGetByIdQueryParams {
    tenantId: string
    API_KEY: string
}

댓글 ID 조회 응답 구조

Copy

interface CommentGetByIdResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'missing-id'
    /** 실패 시 포함됩니다. **/
    reason?: string
    /** 댓글! **/
    comment?: Comment
}

POST /api/v1/comments

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

이 API 엔드포인트는 댓글을 생성하는 기능을 제공합니다.

일반적인 사용 사례는 맞춤 UI, 통합 또는 가져오기입니다.

참고:

원하면 이 API는 댓글 위젯을 "라이브"로 업데이트할 수 있습니다 (이 경우 creditsCost가 1에서 2로 증가합니다).
이메일이 제공되면 이 API는 자동으로 사용자 객체를 시스템에 생성합니다.
다른 이메일을 사용하지만 동일한 사용자 이름을 가진 두 댓글을 저장하려고 하면 두 번째 댓글에 대해 오류가 발생합니다.
만약 parentId를 지정하고 자식 댓글의 notificationSentForParent가 false인 경우, 부모 댓글에 대한 알림을 전송합니다. 이 작업은 매 시간 수행됩니다(전송되는 이메일 수를 줄이기 위해 알림을 일괄 처리합니다).
사용자를 생성할 때 환영 이메일을 보내거나 댓글 확인 이메일을 보내려면 쿼리 매개변수에서 sendEmails를 true로 설정하세요.
이 API로 생성된 댓글은 관리자 앱의 Analytics 및 Moderation 페이지에 표시됩니다.
설정이 켜져 있으면 "bad words"는 댓글 작성자 이름과 댓글 내용에서 여전히 마스킹됩니다.
원하면 이 API로 생성된 댓글은 스팸 검사를 받을 수 있습니다.
Customization Rule 관리자 페이지에서 구성된 최대 댓글 길이 같은 설정은 여기에도 적용됩니다.

댓글 위젯에 표시되기 위해 제출에 필요한 최소 데이터는 다음과 같습니다:

최소 댓글 POST cURL 예제

Copy

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

더 현실적인 요청 예시는 다음과 같습니다:

댓글 POST cURL 예제

Copy

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

댓글 POST 요청 구조

Copy

interface CommentPostQueryParams {
    tenantId: string
    API_KEY: string
    doSpamCheck?: 'true' | 'false'
    /** 댓글이 동일한 urlId를 가진 댓글 위젯 인스턴스를 보는 사용자에게 "라이브"로 표시될지 여부. 참고: 크레딧 비용이 1에서 2로 두 배가 됩니다. **/
    isLive?: 'true' | 'false'
    sendEmails?: 'true' | 'false'
    populateNotifications?: 'true' | 'false'
}

댓글 POST 응답 구조

Copy

interface CommentPostResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-comment' | 'comment-too-big' | 'hash-tags-readonly' | 'mentions-readonly' | 'invalid-user' | 'unauthorized' | 'invalid-date' | 'invalid-name' | 'invalid-name-is-email' | 'banned' | 'invalid-email';
    /** 실패 시 포함됩니다. **/
    reason?: string
    /** 생성된 댓글. **/
    comment?: Comment
    /** 관련된 사용자로, 기존에 존재했을 수도 있고 없었을 수도 있습니다. **/
    user?: User
}

PATCH /api/v1/comments/:id

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

이 API 엔드포인트는 단일 댓글을 업데이트하는 기능을 제공합니다.

참고:

필요에 따라 이 API로 댓글 위젯을 "라이브"로 업데이트할 수 있습니다(이 경우 기본 creditsCost가 1에서 2로 증가합니다).
- 이는 댓글을 페이지 간에 "라이브"로 마이그레이션(예: urlId 변경)하는 데 사용할 수 있습니다.
- 마이그레이션은 페이지를 미리 계산하므로 추가로 2 크레딧이 소모됩니다(이 작업은 CPU 집약적입니다).
생성 API와 달리, 이 API는 이메일이 제공되어도 우리 시스템에 사용자 객체를 자동으로 생성하지 않습니다.
이 API로 업데이트된 댓글은 원하면 스팸 검사 대상이 될 수 있습니다.
Customization Rule 관리자 페이지에서 구성된 최대 댓글 길이와 같은 설정이 여기에도 적용됩니다.
사용자가 자신의 댓글 텍스트를 업데이트하도록 허용하려면 요청 본문에 comment만 지정하면 됩니다. 우리는 결과 commentHTML을 생성합니다.
- comment와 commentHTML을 둘 다 정의하면 HTML을 자동으로 생성하지 않습니다.
- 사용자가 새 텍스트에 멘션이나 해시태그를 추가하면 POST API와 동일하게 처리됩니다.
댓글의 commenterEmail을 업데이트할 때는 userId도 함께 지정하는 것이 좋습니다. 그렇지 않으면 해당 이메일을 가진 사용자가 귀하의 테넌트에 속해 있는지 확인해야 하며, 그렇지 않으면 요청이 실패합니다.

최소 댓글 PATCH cURL 예시

Copy

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

댓글 PATCH 요청 구조

Copy

interface CommentPatchQueryParams {
    tenantId: string
    API_KEY: string
    /** 업데이트를 수행하는 사용자입니다. 필요하면 사용자가 댓글을 편집할 수 있는지 확인하는 데 사용할 수 있습니다. **/
    contextUserId?: string
    /** 새 댓글이 스팸처럼 보이는지 검사할까요? **/
    doSpamCheck?: 'true' | 'false'
    /** 동일한 urlId를 가진 댓글 위젯 인스턴스를 보는 사용자에게 댓글이 "라이브"로 보일지 여부입니다. 참고: 크레딧 비용이 1에서 2로 두 배가 됩니다. **/
    isLive?: 'true' | 'false'
}

댓글 PATCH 응답 구조

Copy

interface CommentPatchResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-comment' | 'comment-too-big' | 'hash-tags-readonly' | 'mentions-readonly' | 'invalid-user' | 'unauthorized' | 'invalid-date' | 'invalid-name' | 'invalid-name-is-email' | 'banned' | 'invalid-email' | 'invalid-input' | 'missing-id' | 'not-found'
    /** 실패 시 포함됩니다. **/
    reason?: string
}

DELETE /api/v1/comments/:id

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

이 API 엔드포인트는 댓글을 삭제하는 기능을 제공합니다.

Notes:

원하는 경우 이 API는 댓글 위젯을 "실시간"으로 업데이트할 수 있습니다(이 경우 creditsCost가 1에서 2로 증가합니다).
이 API는 모든 하위 댓글을 삭제합니다.

댓글 DELETE 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'
}

댓글 DELETE 응답 구조

Copy

interface CommentDeleteResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** 실패 시 포함됩니다. **/
    reason?: string
}

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

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

이 API 엔드포인트는 특정 사용자를 위해 댓글을 신고할 수 있는 기능을 제공합니다.

Notes:

이 호출은 항상 사용자 컨텍스트에서 이루어져야 합니다. 사용자는 FastComments.com 사용자, SSO 사용자, 또는 테넌트 사용자가 될 수 있습니다.
숨김 임계값(flag-to-hide threshold)이 설정되어 있으면, 댓글이 정의된 횟수만큼 신고되면 실시간으로 자동으로 숨김 처리됩니다.
댓글이 자동으로 미승인(숨김) 처리된 후에는 관리자나 모더레이터만이 댓글을 다시 승인할 수 있습니다. 플래그 해제는 댓글을 다시 승인하지 않습니다.

댓글 신고 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'

For anonymous flagging, we must specify an anonUserId. This can be an ID that represents the anonymous session, or a random UUID. This allows us to support flagging and un-flagging comments even if a user is not logged in. This way, the comment can be marked as flagged when comments are fetched with the same anonUserId.

익명 댓글 신고 cURL 예제

Copy

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

댓글 신고 요청 구조

Copy

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

댓글 신고 응답 구조

Copy

interface CommentFlagResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id'
    /** 실패 시 포함됩니다. **/
    reason?: string
    /** 댓글이 너무 많이 신고되어 미승인(숨김) 처리되었나요? **/
    wasUnapproved?: boolean;
}

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

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

이 API 엔드포인트는 특정 사용자가 댓글의 플래그를 해제할 수 있는 기능을 제공합니다.

참고:

이 호출은 항상 사용자 컨텍스트에서 이루어져야 합니다. 사용자는 FastComments.com 사용자, 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를 지정해야 합니다. 이는 익명 세션을 나타내는 ID이거나 임의의 UUID일 수 있습니다.

익명 댓글 플래그 해제 cURL 예제

Copy

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

댓글 플래그 해제 요청 구조

Copy

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

댓글 플래그 해제 응답 구조

Copy

interface CommentUnFlagResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id'
    /** 실패 시 포함됩니다. **/
    reason?: string
}

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

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

이 API 엔드포인트는 특정 댓글을 작성한 사용자를 차단할 수 있는 기능을 제공합니다. FastComments.com 사용자, SSO 사용자, Tenant 사용자가 작성한 댓글로부터의 차단을 지원합니다.

이 호출은 commentIdsToCheck 바디 파라미터를 지원하여, 이 작업 수행 후 클라이언트에 표시될 수 있는 다른 댓글들이 차단/차단 해제되어야 하는지 확인할 수 있습니다.

Notes:

이 호출은 항상 사용자 컨텍스트에서 이루어져야 합니다. 사용자는 FastComments.com 사용자, SSO 사용자, 또는 Tenant 사용자일 수 있습니다.
요청의 userId는 차단을 행하는 사용자입니다. 예: User A가 User B를 차단하려고 합니다. userId=User A와 User B가 작성한 댓글의 id를 전달하세요.
완전히 익명인 댓글(사용자 id 없음, 이메일 없음)은 차단할 수 없으며 에러가 반환됩니다.

댓글 차단 cURL 예제

Copy

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

익명 차단의 경우 anonUserId를 지정해야 합니다. 이는 익명 세션을 나타내는 ID이거나 임의의 UUID일 수 있습니다. 이를 통해 사용자가 로그인하지 않은 경우에도 동일한 anonUserId로 댓글을 가져와 댓글을 차단하는 것을 지원할 수 있습니다.

익명 댓글 차단 cURL 예제

Copy

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

댓글 차단 요청 구조

Copy

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

댓글 차단 응답 구조

Copy

interface CommentBlockResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id' | 'comment-cannot-be-blocked'
    /** 실패 시 포함됩니다. **/
    reason?: string
    /** commentIdsToCheck가 정의된 경우, 이 맵에서 true인 항목들도 차단됩니다. **/
    commentStatuses?: Record<string, boolean>;
}

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

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

이 API 엔드포인트는 특정 댓글을 작성한 사용자의 차단을 해제할 수 있는 기능을 제공합니다. FastComments.com 사용자, SSO 사용자, 및 테넌트 사용자가 작성한 댓글에서의 차단 해제를 지원합니다.

이 작업이 수행된 후 클라이언트에서 잠재적으로 표시되는 다른 댓글들이 차단/차단 해제되어야 하는지 확인하기 위해 commentIdsToCheck 바디 매개변수를 지원합니다.

참고:

이 호출은 항상 사용자의 맥락에서 이루어져야 합니다. 사용자는 FastComments.com 사용자, SSO 사용자, 또는 테넌트 사용자일 수 있습니다.
요청의 userId는 차단을 해제하는 사용자입니다. 예를 들어: User A가 User B의 차단을 해제하려고 합니다. userId=User A와 User B가 작성한 댓글 ID를 전달하세요.
완전히 익명인 댓글(사용자 id 없음, 이메일 없음)은 차단할 수 없으며 오류가 반환됩니다.

댓글 차단 해제 cURL 예시

Copy

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

익명 댓글 차단 해제 cURL 예시

Copy

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

댓글 차단 해제 요청 구조

Copy

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

댓글 차단 해제 응답 구조

Copy

interface CommentUnBlockResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id' | 'comment-cannot-be-blocked'
    /** 실패 시 포함됩니다. **/
    reason?: string
    /** commentIdsToCheck가 정의되어 있으면, 이 맵에서 true인 항목들은 여전히 차단된 상태입니다. false인 경우에는 사용자가 새로고침할 필요가 없도록 댓글의 숨김을 해제해 줄 수 있습니다. **/
    commentStatuses?: Record<string, boolean>;
}

이메일 템플릿 구조

EmailTemplate 객체는 테넌트의 맞춤 이메일 템플릿 구성을 나타냅니다.

시스템은 사용할 이메일 템플릿을 다음 기준으로 선택합니다:

유형 식별자 — 이를 emailTemplateId라고 합니다. 이 값들은 상수입니다.
domain. 먼저 관련 객체(예: Comment)가 속한 도메인에 대한 템플릿을 찾습니다. 일치하는 템플릿이 없으면 domain이 null이거나 *인 템플릿을 찾습니다.

다음은 EmailTemplate 객체의 구조입니다:

이메일 템플릿 구조

Copy

interface EmailTemplate {
    id: string
    tenantId: string
    emailTemplateId: string
    displayName: string
    /** 읽기 전용 **/
    createdAt: string
    /** 읽기 전용 **/
    updatedAt: string
    /** 읽기 전용 **/
    updatedByUserId: string
    /** 템플릿이 연관된 도메인. **/
    domain?: string | '*' | null
    /** EJS 구문으로 된 이메일 템플릿 콘텐츠. **/
    ejs: string
    /** 지원되는 각 로케일에 대해 재정의된 번역 키와 값의 맵. **/
    translationOverridesByLocale: Record<string, Record<string, string>>
    /** 템플릿의 렌더 컨텍스트를 나타내는 객체. **/
    testData: object
}

참고

유효한 emailTemplateId 값은 /definitions 엔드포인트에서 확인할 수 있습니다.
/definitions 엔드포인트에는 기본 번역과 테스트 데이터도 포함되어 있습니다.
템플릿은 구조나 테스트 데이터가 유효하지 않으면 저장에 실패합니다.

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

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

개별 EmailTemplate는 해당 id(emailTemplateId가 아님)로 가져올 수 있습니다.

ID로 EmailTemplate cURL 예제

Copy

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

ID로 EmailTemplate 요청 구조

Copy

interface EmailTemplatesByIdRequestQueryParams {
    tenantId: string
    API_KEY: string
}

ID로 EmailTemplate 응답 구조

Copy

interface EmailTemplateResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'internal' | 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found'
    /** 실패 시 포함됩니다. **/
    reason?: string
    emailTemplate?: EmailTemplate | null
}

GET /api/v1/email-templates

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

이 API는 페이지 매김을 사용하며, page 쿼리 매개변수로 제공합니다. EmailTemplates는 100개씩 페이지로 반환되며, createdAt과 그 다음으로 id로 정렬됩니다.

EmailTemplate cURL 예제

Copy

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

EmailTemplate 요청 구조

Copy

interface EmailTemplatesRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** 가져올 페이지로, 0부터 시작합니다. **/
    page: number
}

EmailTemplate 응답 구조

Copy

interface EmailTemplatesResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** 실패 시 포함됩니다. **/
    reason?: string
    emailTemplates: EmailTemplate[]
}

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

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

이 API 엔드포인트는 id와 업데이트할 속성만 지정하여 이메일 템플릿을 업데이트할 수 있는 기능을 제공합니다.

템플릿을 생성할 때와 동일한 모든 유효성 검사가 적용된다는 점에 유의하세요. 예를 들어:

템플릿은 렌더링되어야 합니다. 각 업데이트 시 이것이 확인됩니다.
동일한 도메인에 대해 중복된 템플릿을 가질 수 없습니다(그렇지 않으면 하나가 조용히 무시됩니다).

EmailTemplate PATCH cURL 예제

Copy

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

EmailTemplate PATCH 요청 구조

Copy

interface EmailTemplatePatchQueryParams {
    tenantId: string
    API_KEY: string
}

EmailTemplate PATCH 응답 구조

Copy

interface EmailTemplatePatchResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'not-found' | 'unexpected-param' | 'invalid-email-template-id' | 'unauthorized' | 'domain-invalid' | 'duplicate' | 'does-not-render';  
    /** 실패 시 포함됩니다. **/
    reason?: string
    /** 업데이트된 이메일 템플릿. **/
    emailTemplate?: EmailTemplate
}

POST /api/v1/email-templates

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

이 API 엔드포인트는 이메일 템플릿을 생성하는 기능을 제공합니다.

Notes:

같은 도메인에서는 동일한 emailTemplateId를 가진 템플릿을 여러 개 가질 수 없습니다.
하지만 와일드카드 템플릿(domain = *)과 동일한 emailTemplateId에 대한 도메인별 템플릿을 동시에 가질 수 있습니다.
여러 도메인이 있거나 테스트용으로 특정 템플릿을 사용하려는 경우(예: domain을 localhost로 설정) 에만 domain을 지정하면 됩니다.
만약 domain을 지정하면 해당 값은 DomainConfig와 일치해야 합니다. 오류가 발생하면 유효한 도메인 목록이 제공됩니다.
템플릿 문법은 EJS이며 500ms 타임아웃으로 렌더링됩니다. 렌더링의 P99는 <5ms 이므로 500ms에 도달하면 문제가 있는 것입니다.
저장하려면 템플릿이 주어진 testData로 렌더링되어야 합니다. 렌더링 오류는 집계되어 대시보드에 보고됩니다(곧 API를 통해서도 제공될 예정입니다).

템플릿을 추가하는 데 필요한 최소 데이터는 다음과 같습니다:

최소 EmailTemplate POST cURL 예제

Copy

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

사이트별 템플릿을 원할 경우 domain을 정의할 수 있습니다:

EmailTemplate POST cURL 예제

Copy

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

EmailTemplate POST 요청 구조

Copy

interface EmailTemplatePostQueryParams {
    tenantId: string
    API_KEY: string
}

EmailTemplate POST 응답 구조

Copy

interface EmailTemplatePostResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'unexpected-param' | 'invalid-email-template-id' | 'domain-invalid' | 'duplicate' | 'does-not-render';
    /** 실패 시 포함됩니다. **/
    reason?: string
    /** 생성된 템플릿. **/
    emailTemplate?: EmailTemplate
}

POST /api/v1/email-templates/render

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

이 API 엔드포인트는 이메일 템플릿을 미리 볼 수 있는 기능을 제공합니다.

최소 EmailTemplate 미리보기 POST cURL 예제

Copy

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

EmailTemplate POST 요청 구조

Copy

interface EmailTemplatePostQueryParams {
    tenantId: string
    API_KEY: string
}

EmailTemplate POST 응답 구조

Copy

interface EmailTemplatePostResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'unexpected-param' | 'does-not-render';
    /** 실패 시 포함됩니다. **/
    reason?: string
    /** 성공 시 렌더링된 HTML. **/
    html?: string
}

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

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

이 경로는 id로 단일 EmailTemplate를 제거합니다.

EmailTemplate 제거 cURL 예제

Copy

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

EmailTemplate 제거 요청 구조

Copy

interface EmailTemplateRequestQueryParams {
    tenantId: string
    API_KEY: string
}

EmailTemplate 제거 응답 구조

Copy

interface EmailTemplateDeleteResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized'
    /** 실패 시 포함됩니다. **/
    reason?: string
}

해시태그 구조

HashTag 객체는 사용자가 남길 수 있는 태그를 나타냅니다. HashTags는 외부 콘텐츠로 연결하거나 관련된 댓글들을 묶는 데 사용할 수 있습니다.

The structure for the HashTag object is as follows:

HashTag 구조

Copy

interface HashTag {
    /** "#" 또는 원하는 문자로 시작해야 합니다. **/
    tag: string
    /** 해시태그가 가리킬 수 있는 선택적 URL입니다. 해시태그로 댓글을 필터링하는 대신, UI는 클릭 시 이 URL로 리디렉션합니다. **/
    url?: string
    /** 읽기 전용 **/
    createdAt: string
}

Notes:

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

GET /api/v1/hash-tags

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

이 API는 page 쿼리 매개변수로 페이지네이션을 제공합니다. HashTags는 tag로 정렬되어 페이지당 100개씩 반환됩니다.

HashTag cURL 예제

Copy

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

HashTag 요청 구조

Copy

interface HashTagsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** 가져올 페이지 (0부터 시작). **/
    page: number
}

HashTag 응답 구조

Copy

interface HashTagsResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** 실패 시 포함됩니다. **/
    reason?: string
    /** 해시태그들! **/
    hashTags: HashTag[]
}

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

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

이 경로는 단일 HashTag를 업데이트할 수 있는 기능을 제공합니다.

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

HashTag 업데이트 요청 구조

Copy

interface HashTagPatchQueryParams {
    tenantId: string
    API_KEY: string
}

HashTag 업데이트 응답 구조

Copy

interface HashTagPatchResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist' | 'url-too-long' | 'invalid-tag' |  'already-exists'
    /** 실패 시 포함됩니다. **/
    reason?: string
    hashTag?: HashTag; // 성공 시 업데이트된 전체 해시태그를 반환합니다.
}

POST /api/v1/hash-tags

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

이 라우트는 단일 HashTag를 추가하는 기능을 제공합니다.

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

HashTag 생성 요청 구조

Copy

interface HashTagPostQueryParams {
    tenantId: string
    API_KEY: string
}

HashTag 생성 응답 구조

Copy

interface HashTagPostResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist' | 'url-too-long' | 'invalid-tag'
    /** 실패 시 포함됩니다. **/
    reason?: string
    hashTag?: HashTag; // 성공 시 생성된 전체 해시태그를 반환합니다.
}

POST /api/v1/hash-tags/bulk

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

이 경로는 최대 100개의 HashTag 객체를 한 번에 추가할 수 있는 기능을 제공합니다.

HashTag 일괄 생성 cURL 예제

Copy

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

HashTag 일괄 생성 요청 구조

Copy

interface HashTagPostQueryParams {
    tenantId: string
    API_KEY: string
}

HashTag 일괄 생성 응답 구조

Copy

interface HashTagBulkPostResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist' | 'url-too-long' | 'invalid-tag'
    /** 실패 시 포함됩니다. **/
    reason?: string
    results?: HashTagPostResponse[]; // 제공된 각 태그에 대해 HashTagPostResponse 객체의 목록을 반환합니다.
}

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

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

이 라우트는 제공된 태그로 HashTag 사용자를 제거합니다.

자동 HashTag 생성이 비활성화되지 않은 한, 사용자가 댓글 작성 시 해시태그를 제공하면 해시태그가 다시 생성될 수 있습니다.

HashTag 제거 cURL 예제

Copy

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

HashTag 제거 요청 구조

Copy

interface HashTagDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

HashTag 제거 응답 구조

Copy

interface HashTagDeleteResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist'
    /** 실패 시 포함됩니다. **/
    reason?: string
}

모더레이터 구조

Moderator 객체는 모더레이터에 대한 구성을 나타냅니다.

모더레이터에는 세 가지 유형이 있습니다:

isCommentModeratorAdmin 플래그를 가진 관리자 사용자.
isCommentModeratorAdmin 플래그를 가진 SSO 사용자.
초대로 모더레이터가 된 일반 댓글 작성자 또는 FastComments.com 사용자.

Moderator 구조는 사용 사례 3의 중재 상태를 나타내는 데 사용됩니다.

API를 통해 사용자를 모더레이터로 초대하려면 Moderator API를 사용하여 Moderator를 생성하고 그들을 inviting 하십시오.

사용자에게 FastComments.com 계정이 없으면 초대 이메일이 계정 설정을 돕습니다. 이미 계정이 있는 경우 해당 테넌트에 대한 중재 접근 권한이 부여되고 Moderator 객체의 userId가 해당 사용자를 가리키도록 업데이트됩니다. 이 경우 해당 사용자 계정은 본인 소유이며 FastComments.com에서 관리되므로, 해당 사용자에 대한 API 접근 권한은 없습니다.

사용자 계정을 완전히 관리해야 하는 경우, SSO를 사용하거나 그들을 Tenant User로 추가한 다음 Moderator 객체를 추가하여 통계를 추적하는 것을 권장합니다.

Moderator 구조는 사용 사례 1 및 2에 대한 통계 추적 메커니즘으로 사용할 수 있습니다. 사용자를 생성한 후 userId가 정의된 Moderator 객체를 추가하면 해당 통계가 Comment Moderators Page에서 추적됩니다.

Moderator 객체의 구조는 다음과 같습니다:

Moderator 구조

Copy

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

GET /api/v1/moderators/:id

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

이 경로는 해당 id의 단일 모더레이터를 반환합니다.

ID로 모더레이터 조회 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'
    /** 실패 시 포함됨. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** 실패 시 포함됨. **/
    reason?: string
    moderator?: Moderator
}

GET /api/v1/moderators

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

이 API는 페이징을 사용하며, skip 쿼리 매개변수로 제공됩니다. 모더레이터는 createdAt 및 id 순으로 정렬되어 한 페이지에 100명씩 반환됩니다.

요금은 반환된 모더레이터 수에 따라 계산되며, 반환된 모더레이터 10명당 1 credit per 10의 비용이 발생합니다.

모더레이터 cURL 예제

Copy

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

모더레이터 요청 구조

Copy

interface ModeratorsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** 페이징을 위해 건너뛸 모더레이터 수. **/
    skip?: number
}

모더레이터 응답 구조

Copy

interface ModeratorsResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** 실패 시 포함됩니다. **/
    reason?: string
    moderators?: Moderator[]
}

PATCH /api/v1/moderators/:id

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

이 API 엔드포인트는 id로 Moderator를 업데이트할 수 있는 기능을 제공합니다.

Moderator를 업데이트할 때 다음과 같은 제한이 있습니다:

Moderator를 업데이트할 때 다음 값들은 제공할 수 없습니다:
- acceptedInvite
- markReviewedCount
- deletedCount
- markedSpamCount
- approvedCount
- editedCount
- bannedCount
- verificationId
- createdAt
userId가 지정된 경우, 해당 사용자가 존재해야 합니다.
userId가 지정된 경우, 해당 사용자는 쿼리 매개변수에 지정된 동일한 tenantId에 속해야 합니다.
동일한 테넌트 내의 두 명의 모더레이터는 동일한 email로 추가할 수 없습니다.
Moderator에 연관된 tenantId는 변경할 수 없습니다.

Moderator PATCH cURL 예제

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

Moderator PATCH 요청 구조

Copy

interface ModeratorPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Moderator PATCH 응답 구조

Copy

interface ModeratorPatchResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'name-required' | 'email-required' | 'unexpected-param' | 'not-found';  
    /** 실패 시 포함됩니다. **/
    reason?: string
}

POST /api/v1/moderators

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

이 경로는 단일 Moderator를 추가할 수 있는 기능을 제공합니다.

Moderator 생성에는 다음과 같은 제한이 있습니다:

name과 email은 항상 제공되어야 합니다. userId는 선택 사항입니다.
Moderator를 생성할 때 다음 값들은 제공할 수 없습니다:
- acceptedInvite
- markReviewedCount
- deletedCount
- markedSpamCount
- approvedCount
- editedCount
- bannedCount
- verificationId
- createdAt
userId가 지정된 경우, 해당 사용자는 존재해야 합니다.
userId가 지정된 경우, 해당 사용자는 쿼리 매개변수에 지정된 동일한 tenantId에 속해야 합니다.
동일한 테넌트 내에서 두 명의 모더레이터는 같은 email로 추가될 수 없습니다.

이메일만 알고 있는 사용자에 대해 Moderator를 생성할 수 있습니다:

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를 생성할 수 있습니다:

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

Moderator 생성 요청 구조

Copy

interface ModeratorPostQueryParams {
    tenantId: string
    API_KEY: string
}

Moderator 생성 응답 구조

Copy

interface ModeratorPostResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'name-required' | 'email-required' | 'unexpected-param' | 'not-found'
    /** 실패 시 포함됩니다. **/
    reason?: string
    moderator?: Moderator; // 성공 시 생성된 전체 모더레이터를 반환합니다.
}

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

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

이 경로는 단일 Moderator를 초대할 수 있는 기능을 제공합니다.

다음 제한 사항이 Moderator에게 초대 이메일을 보내는 데 적용됩니다:

Moderator는 이미 존재해야 합니다.
fromName은 100 characters보다 길 수 없습니다.

참고:

제공된 이메일을 가진 사용자가 이미 존재하면, 해당 사용자는 테넌트의 댓글을 관리하도록 초대됩니다.
제공된 이메일을 가진 사용자가 존재하지 않는 경우, 초대 링크는 계정 생성 절차로 안내합니다.
초대는 30 days 후에 만료됩니다.

이메일만 알고 있는 사용자에 대해 Moderator를 생성할 수 있습니다:

Moderator 초대 cURL 예제

Copy

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

이것은 다음과 같은 이메일을 보냅니다: Bob at TenantName is inviting you to be a moderator...

Moderator 초대 요청 구조

Copy

interface ModeratorSendInviteQueryParams {
    tenantId: string
    API_KEY: string
    /** 사용자에게 전송되는 이메일은 이 이름에서 보낸 것처럼 표시됩니다. **/
    fromName: string
}

Moderator 초대 응답 구조

Copy

interface ModeratorSendInviteResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'not-found | 'from-name-required' | 'from-name-invalid'
    /** 실패 시 포함됩니다. **/
    reason?: string
}

DELETE /api/v1/moderators/:id

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

이 경로는 id로 Moderator를 제거합니다.

Moderator 제거 cURL 예제

Copy

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

Moderator 제거 요청 구조

Copy

interface ModeratorDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Moderator 제거 응답 구조

Copy

interface ModeratorDeleteResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found'
    /** 실패 시 포함됩니다. **/
    reason?: string
}

알림 수 구조

A NotificationCount object represents the unread notification count and metadata for a user.

If there are no unread notifications, there will be no NotificationCount for the user.

NotificationCount objects are created automatically and cannot be created via the API. They also expire after one year.

You can clear a user's unread notification count by deleting their NotificationCount.

The structure for the NotificationCount object is as follows:

NotificationCount 구조

Copy

interface NotificationCount {
    id: string // 사용자 id
    count: number
    createdAt: string // 날짜 문자열
    expireAt: string // 날짜 문자열
}

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

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

이 라우트는 사용자 ID로 단일 NotificationCount를 반환합니다. SSO를 사용하는 경우 사용자 ID 형식은 <tenant id>:<user id>입니다.

읽지 않은 알림이 없으면 NotificationCount가 없으므로 404를 받게 됩니다.

notifications/count와 달리 훨씬 빠르지만 필터링은 허용하지 않습니다.

NotificationCount ID별 cURL 예제

Copy

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

NotificationCount 요청 구조

Copy

interface NotificationCountGetQueryParams {
    tenantId: string
    API_KEY: string
}

NotificationCount 응답 구조

Copy

interface NotificationCountGetResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'not-found'
    /** 실패 시 포함됩니다. **/
    reason?: string
    data?: NotificationCount
}

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

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

이 경로는 사용자 id로 단일 NotificationCount를 삭제합니다. SSO를 사용하는 경우, 사용자 id는 <tenant id>:<user id> 형식입니다.

이 작업은 사용자의 읽지 않은 알림 수를 초기화합니다(댓글 위젯의 빨간 벨이 사라지고 카운트가 사라집니다).

NotificationCount 삭제 cURL 예제

Copy

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

NotificationCount 삭제 요청 구조

Copy

interface NotificationCountDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

NotificationCount 삭제 응답 구조

Copy

interface NotificationCountDeleteResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'not-found'
    /** 실패 시 포함됩니다. **/
    reason?: string
}

알림 구조

A Notification object represents a notification for a user.

Notification objects are created automatically and cannot be created via the API. They also expire after one year. Notifications cannot be deleted. They can however be updated to set viewed to false, and you can query by viewed.

A user may also opt out of notifications for a specific comment by setting optedOut in the notification to true. You can opt in again by setting it to false.

There are different notification types - check relatedObjectType and type.

The ways notifications are created is quite flexible and can be triggered by many scenarios (see NotificationType).

As of today, the existence of a Notification does not actually imply an email is or should be sent. Rather, the notifications are used for the notification feed and related integrations.

The structure for the Notification object is as follows:

알림 구조

Copy

enum NotificationObjectType {
    Comment = 0,
    Profile = 1,
    Tenant = 2
}
enum NotificationType {
    /** 누군가가 당신에게 답글을 남긴 경우. **/
    RepliedToMe = 0,
    /** 당신이 댓글을 남긴 스레드의 어느 곳(자식의 자식 등 포함)에서 누군가가 답글을 남긴 경우. **/
    RepliedTransientChild = 1,
    /** 당신의 댓글이 업보트된 경우. **/
    VotedMyComment = 2,
    /** 당신이 구독한 페이지의 루트에 새 댓글이 달린 경우. **/
    SubscriptionReplyRoot = 3,
    /** 누군가가 당신의 프로필에 댓글을 남긴 경우. **/
    CommentedOnProfile = 4,
    /** 당신에게 DM(다이렉트 메시지)이 도착한 경우. **/
    DirectMessage = 5,
    /** TrialLimits는 테넌트 사용자 전용입니다. **/
    TrialLimits = 6,
    /** 당신이 @언급된 경우. **/
    Mentioned = 7
}
interface Notification {
    id: string
    tenantId: string
    /** With SSO, the user id is in the format `<tenant id>:<user id>`. **/
    userId?: string
    /** SSO를 사용할 때에는 `userId`만 신경 쓰면 됩니다. **/
    anonUserId?: string
    /** urlId는 거의 항상 정의됩니다. 테넌트 수준의 알림에는 선택적이며, 이는 드뭅니다. **/
    urlId?: string
    /** URL은 알림 출처로 빠르게 이동하기 위해 캐시됩니다. **/
    url?: string
    /** 페이지 제목은 알림 출처를 빠르게 확인하기 위해 캐시됩니다. **/
    pageTitle?: string
    relatedObjectType: NotificationObjectType
    /** 예: 댓글 ID. **/
    relatedObjectId: string
    viewed: boolean
    createdAt: string // 날짜 문자열
    type: NotificationType
    fromCommentId?: string
    fromVoteId?: string
    /** fromUserName 및 fromUserAvatarSrc는 알림을 빠르게 표시하기 위해 여기에 캐시됩니다. 사용자가 업데이트되면 함께 업데이트됩니다. **/
    fromUserName: string
    fromUserId: string
    fromUserAvatarSrc?: string
    /** 이 값을 true로 설정하면 이 객체에 대한 알림 수신을 중단합니다. **/
    optedOut?: boolean
}

GET /api/v1/notifications

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

이 라우트는 createdAt을 기준으로 최신 순으로 정렬된 최대 30개의 Notification 객체를 반환합니다.

userId로 필터링할 수 있습니다. SSO의 경우 사용자 ID는 <tenant id>:<user id> 형식입니다.

사용자 읽지 않은 알림 cURL 예제

Copy

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

알림 요청 구조

Copy

interface NotificationsGetQueryParams {
    tenantId: string
    API_KEY: string
    /** 레코드를 건너뛰어 페이지네이션합니다. **/
    skip?: number
    /** 사용자별 필터. **/
    userId?: string
    /** urlId로 필터링. **/
    urlId?: string
    /** 원본 댓글로 필터링. **/
    fromCommentId?: string
    /** 읽음/읽지 않음으로 필터링. **/
    viewed?: 'true' | 'false'
    /** 유형으로 필터링. **/
    type?: NotificationType
}

알림 응답 구조

Copy

interface NotificationsGetResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** 실패 시 포함됩니다. **/
    reason?: string
    notifications?: Notification[]
}

GET /api/v1/notifications/count

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

이 라우트는 count 매개변수에 알림 수를 담은 객체를 반환합니다.

이 라우트는 /notification-count/보다 느리고 크레딧 비용이 두 배이지만 더 많은 차원으로 필터링할 수 있습니다.

/notifications 엔드포인트와 동일한 매개변수(예: userId)로 필터링할 수 있습니다. SSO를 사용하는 경우 user id는 <tenant id>:<user id> 형식입니다.

사용자 읽지 않은 알림 수 cURL 예제

Copy

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

특정 페이지의 사용자 읽지 않은 알림 수 cURL 예제

Copy

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

알림 수 요청 구조

Copy

interface NotificationCountGetQueryParams {
    tenantId: string
    API_KEY: string
    /** 사용자로 필터링. **/
    userId?: string
    /** urlId로 필터링. **/
    urlId?: string
    /** 출처 댓글로 필터링. **/
    fromCommentId?: string
    /** 읽음 여부로 필터링. **/
    viewed?: 'true' | 'false'
    /** 타입으로 필터링. **/
    type?: NotificationType
}

알림 수 응답 구조

Copy

interface NotificationCountGetResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** 실패 시 포함됩니다. **/
    reason?: string
    count?: number
}

PATCH /api/v1/notifications/:id

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

이 API 엔드포인트는 id로 Notification을 업데이트할 수 있는 기능을 제공합니다.

Notification을 업데이트할 때 다음 제한이 있습니다:

다음 필드만 업데이트할 수 있습니다:
- viewed
- optedOut

Notification PATCH cURL 예제

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

Notification PATCH 요청 구조

Copy

interface NotificationPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Notification PATCH 응답 구조

Copy

interface NotificationPatchResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'unauthorized' | 'not-found';  
    /** 실패 시 포함됩니다. **/
    reason?: string
}

페이지 구조

A Page 객체는 여러 댓글이 속할 수 있는 페이지를 나타냅니다. 이 관계는 urlId로 정의됩니다.

A Page는 페이지 제목, 댓글 수, 및 urlId와 같은 정보를 저장합니다.

Page 객체의 구조는 다음과 같습니다:

페이지 구조

Copy

interface Page {
    id: string
    urlId: string
    url: string
    title?: string
    createdAt: string
    commentCount: number
    rootCommentCount: number
    /** 이를 null로 설정하면 모든 SSO 사용자가 페이지를 볼 수 있습니다. 빈 리스트는 모든 사용자에게 닫혀 있음을 의미합니다. **/
    accessibleByGroupIds?: string[] | null
    /** 이 페이지가 새 댓글 작성에 대해 닫혀 있나요? **/
    isClosed?: boolean
}

GET /api/v1/pages

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

현재 계정과 연결된 모든 페이지(또는 /by-url-id를 통해 단일 페이지)만 가져올 수 있습니다. 보다 세분화된 검색을 원하시면, 문의해 주세요.

페이지 cURL 예제

Copy

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

페이지 요청 구조

Copy

interface PagesRequestQueryParams {
    tenantId: string
    API_KEY: string
}

페이지 응답 구조

Copy

interface PagesResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** 실패 시 포함됩니다. **/
    reason?: string
    pages: Page[]
}

Helpful Tip

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

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

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

개별 페이지는 해당 urlId로 가져올 수 있습니다. 이는 페이지 제목이나 댓글 수를 조회하는 데 유용합니다.

URL ID로 페이지 조회 cURL 예제

Copy

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

URL ID로 페이지 요청 구조

Copy

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

URL ID로 페이지 응답 구조

Copy

interface PagesResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id'
    /** 실패 시 포함됩니다. **/
    reason?: string
    page?: Page[] | null
}

유용한 팁

urlId과 같은 값은 URI 인코딩해야 합니다.

PATCH /api/v1/pages/:id

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

이 라우트는 단일 Page를 업데이트할 수 있는 기능을 제공합니다. 해당 댓글들이 업데이트됩니다.

페이지 업데이트 cURL 예제

Copy

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

페이지 업데이트 요청 구조

Copy

interface PagePatchQueryParams {
    tenantId: string
    API_KEY: string
}

페이지 업데이트 응답 구조

Copy

interface PagePatchResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'missing-id' | 'page-does-not-exist' | 'empty-request' | 'internal' | 'invalid-input' | 'invalid-title' | 'extra-params' | 'accessible-by-group-ids-not-array' | 'too-many-group-ids' | 'group-id-too-large'
    /** 실패 시 포함됩니다. **/
    reason?: string
    user?: Page; // 성공 시 전체 업데이트된 페이지를 반환합니다.
}

참고

Page 객체의 일부 매개변수는 자동으로 업데이트됩니다. 이러한 항목에는 카운트와 title 속성이 포함됩니다. 카운트는 계산된 값이므로 API를 통해 업데이트할 수 없습니다. 페이지 title은 API를 통해 설정할 수 있지만, 동일한 urlId를 가진 페이지에서 댓글 위젯을 사용하고 페이지 제목이 다를 경우 덮어써질 수 있습니다.

POST /api/v1/pages

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

이 API 엔드포인트는 페이지를 생성하는 기능을 제공합니다.

일반적인 사용 사례는 접근 제어입니다.

참고:

댓글 스레드에 댓글을 달았거나, Comment를 생성하는 API를 호출했다면, 이미 Page 객체를 생성한 것입니다! You can try fetching it via the /by-url-id Page route, passing in the same urlId passed to the comment widget.
The Page structure contains some calculated values. Currently, these are commentCount and rootCommentCount. They are populated automatically and cannot be set by the API. Attempting to do so will cause the API to return an error.

페이지 POST cURL 예제

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 요청 구조

Copy

interface PagePostQueryParams {
    tenantId: string
    API_KEY: string
}

페이지 POST 응답 구조

Copy

interface PagePostResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-request' | 'internal' | 'invalid-input' | 'invalid-title' | 'extra-params' | 'accessible-by-group-ids-not-array' | 'too-many-group-ids' | 'group-id-too-large';  
    /** 실패 시 포함됩니다. **/
    reason?: string
    /** 생성된 페이지. **/
    page?: Page
}

DELETE /api/v1/pages/:id

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

이 라우트는 id로 단일 페이지를 제거합니다.

동일한 urlId를 가진 페이지의 댓글 위젯과 상호작용하면 Page가 원활하게 재생성된다는 점에 유의하세요.

페이지 제거 cURL 예제

Copy

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

페이지 제거 요청 구조

Copy

interface PageDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

페이지 제거 응답 구조

Copy

interface PageDeleteResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'page-does-not-exist'
    /** 실패 시 포함됩니다. **/
    reason?: string
}

보류 중인 웹후크 이벤트 구조

A PendingWebhookEvent 객체는 대기 중인 큐에 저장된 웹훅 이벤트를 나타냅니다.

PendingWebhookEvent 객체는 자동으로 생성되며 API를 통해 수동으로 생성할 수 없습니다. 또한 1년 후 만료됩니다. 큐에서 작업을 제거하는 삭제가 가능합니다.

이벤트 유형에는 여러 가지가 있습니다 - eventType (OutboundSyncEventType) 및 type (OutboundSyncType)을 확인하세요.

이 API의 일반적인 사용 사례 중 하나는 맞춤형 모니터링 구현입니다. 주기적으로 /count 엔드포인트를 호출하여 주어진 필터에 대한 미해결 수를 폴링할 수 있습니다.

PendingWebhookEvent 객체의 구조는 다음과 같습니다:

PendingWebhookEvent 구조

Copy

enum OutboundSyncEventType {
    Create: 0,
    Delete: 1,
    Update: 2
}
enum OutboundSyncType {
    /** WordPress 전용 동기화 작업. **/
    WP: 0,
    Webhook: 1
}
interface PendingWebhookEvent {
    id: string
    /** 이벤트와 연관된 댓글 ID. **/
    commentId: string
    /** 이벤트 시점의 댓글 객체. 2023년 11월부터 추가하기 시작했습니다. **/
    comment: Comment
    /** 댓글과 연결될 수 있는 외부 ID. **/
    externalId: string | null
    createdAt: Date
    tenantId: string
    attemptCount: number
    /** 첫 시도 전에 설정되며, 실패할 때마다 갱신됩니다. **/
    nextAttemptAt: Date
    /** 생성, 삭제, 또는 업데이트 이벤트인지 여부. **/
    eventType: OutboundSyncEventType
    /** 수행할 동기화 유형 (WordPress, API 호출 등). **/
    type: OutboundSyncType
    /** 댓글과 일치한 도메인. 이 도메인을 사용하여 API 키를 선택합니다. **/
    domain: string
    /** 발생한 마지막 오류. 이 타입은 구체적으로 정의되어 있지 않으며 발생한 내용을 그대로 덤프한 것입니다. 일반적으로 statusCode, body, headers 맵을 포함하는 객체를 담고 있습니다. **/
    lastError: object | null
}

GET /api/v1/pending-webhook-events

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

이 경로는 pendingWebhookEvents 매개변수 아래의 대기 중인 웹후크 이벤트 목록을 반환합니다.

이 API는 페이징을 사용하며, 이는 skip 매개변수로 제공됩니다. PendingWebhookEvents는 100개씩 페이지로 반환되며 createdAt을 기준으로 최신 순으로 정렬됩니다.

PendingWebhookEvent cURL 예제

Copy

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

PendingWebhookEvent 요청 구조

Copy

interface PendingWebhookEventsGetQueryParams {
    tenantId: string
    API_KEY: string
    commentId?: string
    externalId?: string
    eventType?: OutboundSyncEventType
    type?: OutboundSyncType
    domain?: string
    /** 지정된 숫자보다 시도 횟수가 큰 이벤트를 쿼리합니다. **/
    attemptCountGT?: number
}

PendingWebhookEvent 응답 구조

Copy

interface PendingWebhookEventsGetResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** 실패 시 포함됩니다. **/
    reason?: string
    pendingWebhookEvents?: PendingWebhookEvent[]
}

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

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

이 경로는 보류 중인 웹훅 이벤트 수를 count 매개변수로 포함한 객체를 반환합니다.

필터는 /pending-webhook-events 엔드포인트와 동일한 매개변수로 할 수 있습니다.

PendingWebhookEvent 카운트 cURL 예제

Copy

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

PendingWebhookEvent 카운트 요청 구조

Copy

interface PendingWebhookEventsCountQueryParams {
    tenantId: string
    API_KEY: string
    commentId?: string
    externalId?: string
    eventType?: OutboundSyncEventType
    type?: OutboundSyncType
    domain?: string
    /** 지정된 숫자보다 시도 횟수가 큰 이벤트를 쿼리합니다. **/
    attemptCountGT?: number
}

PendingWebhookEvent 카운트 응답 구조

Copy

interface PendingWebhookEventsCountResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** 실패 시 포함됩니다. **/
    reason?: string
    count?: number
}

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

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

이 경로는 단일 PendingWebhookEvent를 삭제할 수 있습니다.

대량 삭제가 필요한 경우, 페이징을 사용하여 GET API를 호출한 다음 이 API를 순차적으로 호출하세요.

PendingWebhookEvent 삭제 cURL 예제

Copy

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

PendingWebhookEvent 삭제 요청 구조

Copy

interface PendingWebhookEventDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

PendingWebhookEvent 삭제 응답 구조

Copy

interface PendingWebhookEventDeleteResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** 실패 시 포함됩니다. **/
    reason?: string
}

SSO 사용자 구조

FastComments는 사용하기 쉬운 SSO 솔루션을 제공합니다. HMAC 기반 통합으로 사용자의 정보를 업데이트하는 것은 사용자가 업데이트된 페이로드로 페이지를 로드하도록 하는 것만큼 간단합니다.

그러나 응용 프로그램의 일관성을 높이기 위해 해당 흐름 외부에서 사용자를 관리하는 것이 바람직할 수 있습니다.

SSO User API는 우리가 SSOUsers라고 부르는 객체를 CRUD할 수 있는 방법을 제공합니다. 이 객체들은 일반 Users와 다르며 타입 안전성을 위해 분리되어 관리됩니다.

SSOUser 객체의 구조는 다음과 같습니다:

SSOUser 구조

Copy

interface SSOUser {
    id: string
    username: string
    email?: string
    websiteUrl?: string
    signUpDate: number
    createdFromUrlId?: string
    loginCount?: number
    avatarSrc?: string
    optedInNotifications?: boolean
    optedInSubscriptionNotifications?: boolean
    displayLabel?: string
    displayName?: string
    isAccountOwner?: boolean // 관리자 권한 - 이 플래그가 설정된 SSO 사용자는 SSO 관리자으로 과금됩니다 (일반 SSO 사용자와 별도)
    isAdminAdmin?: boolean // 관리자 권한 - 이 플래그가 설정된 SSO 사용자는 SSO 관리자으로 과금됩니다 (일반 SSO 사용자와 별도)
    isCommentModeratorAdmin?: boolean // 중재자 권한 - 이 플래그가 설정된 SSO 사용자는 SSO 중재자로 과금됩니다 (일반 SSO 사용자와 별도)
    /** null이면 액세스 제어가 사용자에게 적용되지 않습니다. 빈 리스트이면 이 사용자는 어떤 페이지도 볼 수 없고 다른 사용자를 @mention할 수도 없습니다. **/
    groupIds?: string[] | null
    createdFromSimpleSSO?: boolean
    /** 다른 사용자가 이 사용자의 프로필에서 댓글을 포함한 활동을 보지 못하게 합니다. 기본값은 안전한 프로필을 제공하기 위해 true입니다. **/
    isProfileActivityPrivate?: boolean
    /** 다른 사용자가 이 사용자의 프로필에 댓글을 남기거나 기존 프로필 댓글을 보는 것을 허용하지 않습니다. 기본값은 false입니다. **/
    isProfileCommentsPrivate?: boolean
    /** 다른 사용자가 이 사용자에게 직접 메시지를 보내는 것을 허용하지 않습니다. 기본값은 false입니다. **/
    isProfileDMDisabled?: boolean
    karma?: number
    /** 사용자 배지에 대한 선택적 구성. **/
    badgeConfig?: {
        /** 사용자에게 할당할 배지 ID의 배열. 최대 30개의 배지로 제한됩니다. 순서가 유지됩니다. **/
        badgeIds: string[]
        /** true이면 표시된 모든 기존 배지를 제공된 배지로 대체합니다. false이면 기존 배지에 추가합니다. **/
        override?: boolean
        /** true이면 테넌트 구성에서 배지 표시 속성을 업데이트합니다. **/
        update?: boolean
    }
}

SSO 사용자 청구

SSO 사용자는 권한 플래그에 따라 다르게 과금됩니다:

Regular SSO Users: 관리자 또는 중재자 권한이 없는 사용자는 일반 SSO 사용자로 과금됩니다
SSO Admins: isAccountOwner 또는 isAdminAdmin 플래그가 있는 사용자는 SSO 관리자로 별도 과금됩니다 (일반 테넌트 관리자와 동일한 요율)
SSO Moderators: isCommentModeratorAdmin 플래그가 있는 사용자는 SSO 중재자로 별도 과금됩니다 (일반 중재자와 동일한 요율)

중요: 이중 과금을 방지하기 위해 시스템은 이메일 주소를 기준으로 SSO 사용자와 일반 테넌트 사용자 및 중재자를 자동으로 중복 제거합니다. SSO 사용자가 일반 테넌트 사용자나 중재자와 동일한 이메일을 가지고 있으면 두 번 과금되지 않습니다.

액세스 제어

사용자는 그룹으로 나눌 수 있습니다. 이것이 groupIds 필드의 목적이며 선택적입니다.

@멘션

기본적으로 @mentions는 @ 문자를 입력하면 다른 sso 사용자를 검색하기 위해 username을 사용합니다. displayName이 사용되면 displayName에 일치하는 결과가 있을 때 username과 일치하는 결과는 무시되며 @mention 검색 결과는 displayName을 사용합니다.

FastComments에서는 사용자가 댓글 위젯의 벨 아이콘을 클릭하고 구독을 클릭하면 페이지를 구독할 수 있습니다.

일반 사용자와 함께 우리는 알림 설정에 따라 알림 이메일을 전송합니다.

SSO 사용자와 함께, 하위 호환성을 위해 이를 분리합니다. 사용자는 optedInSubscriptionNotifications를 true로 설정한 경우에만 이러한 추가 구독 알림 이메일을 받게 됩니다.

배지

badgeConfig 속성을 사용하여 SSO 사용자에게 배지를 할당할 수 있습니다. 배지는 댓글에서 사용자 이름 옆에 표시되는 시각적 표시기입니다.

badgeIds - 사용자에게 할당할 배지 ID의 배열입니다. 이는 FastComments 계정에서 생성된 유효한 배지 ID여야 합니다. 30개의 배지로 제한됩니다.
override - true이면 댓글에 표시된 모든 기존 배지가 제공된 배지로 대체됩니다. false이거나 생략된 경우 제공된 배지가 기존 배지에 추가됩니다.
update - true이면 사용자가 로그인할 때마다 테넌트 구성에서 배지 표시 속성이 업데이트됩니다.

GET /api/v1/sso-users

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

이 라우트는 SSO 사용자들을 페이지당 100개로 반환합니다. 페이지네이션은 skip 파라미터로 제공합니다. 사용자들은 signUpDate와 id로 정렬됩니다.

SSOUsers cURL 예제

Copy

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

SSOUsers 요청 구조

Copy

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

SSOUsers 응답 구조

Copy

interface SSOUsersResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** 실패 시 포함됩니다. **/
    reason?: string
    users: SSOUser[]
}

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

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

이 경로는 사용자 ID로 단일 SSO 사용자를 반환합니다.

SSOUser ID로 조회하는 cURL 예제

Copy

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

SSOUser 요청 구조

Copy

interface SSOUserRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
}

SSOUser 응답 구조

Copy

interface SSOUserByIdResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'user-does-not-exist'
    /** 실패 시 포함됩니다. **/
    reason?: string
    user: SSOUser
}

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

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

이 경로는 이메일로 단일 SSO 사용자를 반환합니다.

SSOUser 이메일별 cURL 예제

Copy

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

SSOUser 요청 구조

Copy

interface SSOUserRequestByEmailQueryParams {
    tenantId: string
    API_KEY: string
}

SSOUser 응답 구조

Copy

interface SSOUserByEmailResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-email' | 'user-does-not-exist'
    /** 실패 시 포함됩니다. **/
    reason?: string
    user: SSOUser
}

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

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

이 경로는 단일 SSO 사용자를 업데이트할 수 있는 기능을 제공합니다.

SSOUser 업데이트 cURL 예제

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
    /** 이메일 또는 사용자 이름을 변경할 때, 사용자의 댓글도 함께 업데이트하려면 이 값을 'true'로 설정할 수 있습니다. 이 경우 크레딧 비용이 두 배가 됩니다. **/
    updateComments: 'true' | 'false'
}

SSOUser 업데이트 응답 구조

Copy

interface SSOUserPatchResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-does-not-exist'
    /** 실패 시 포함됩니다. **/
    reason?: string
    user?: SSOUser; // 성공 시 업데이트된 전체 사용자를 반환합니다.
}

POST /api/v1/sso-users

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

이 경로는 단일 SSO 사용자를 생성합니다.

동일한 ID로 두 사용자를 생성하려 하면 오류가 발생합니다.

SSOUser 생성 cURL 예제

Copy

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

In this example we specify groupIds for access control, but this is optional.

SSOUser 생성 요청 구조

Copy

interface SSOUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

SSOUser 생성 응답 구조

Copy

interface SSOUserPostResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-exists'
    /** 실패 시 포함됩니다. **/
    reason?: string
    user?: SSOUser; // 성공 시 생성된 사용자를 반환합니다.
}

통합 참고

API로 전달된 데이터는 다른 SSO User HMAC 페이로드를 전달하는 것만으로 간단히 덮어쓸 수 있습니다. For example, if API를 통해 username을 설정했지만 페이지 로드 시 SSO 흐름에서 다른 username을 전달하면, 우리는 자동으로 업데이트 해당 사용자의 username.

We will not update user parameters in this flow unless you explicitly specify them or set them to null (not undefined).

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

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

이 경로는 단일 SSO 사용자를 업데이트할 수 있는 기능을 제공합니다.

SSOUser 업데이트 cURL 예제

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
    /** 이메일 또는 사용자 이름이 변경될 때, 이 값을 true로 설정하면 사용자의 댓글도 함께 업데이트합니다. 이 경우 크레딧 비용은 두 배가 됩니다. **/
    updateComments: 'true' | 'false'
}

SSOUser 업데이트 응답 구조

Copy

interface SSOUserPutResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-exists'
    /** 실패 시 포함됩니다. **/
    reason?: string
    user?: SSOUser; // 성공 시 업데이트된 사용자를 반환합니다.
}

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

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

이 라우트는 id로 단일 SSO 사용자를 제거합니다.

이 사용자의 페이로드로 댓글 위젯을 다시 로드하면 사용자가 원활하게 재생성됩니다.

사용자의 댓글을 삭제하려면 deleteComments 쿼리 매개변수를 통해 가능합니다. 이 값이 true인 경우에 유의하세요:

사용자의 모든 댓글이 실시간으로 삭제됩니다.
모든 child (이제 고아가 된) 댓글은 각 댓글의 연관된 페이지 설정에 따라 삭제되거나 익명화됩니다. 예를 들어 스레드 삭제 모드가 "anonymize"이면 답글은 남아 있고 사용자의 댓글만 익명화됩니다. 이는 commentDeleteMode가 Remove(기본값)일 때만 적용됩니다.
creditsCost는 2가 됩니다.

익명화된 댓글

사용자의 댓글을 유지하되 commentDeleteMode=1로 설정하여 간단히 익명화할 수 있습니다.

사용자의 댓글이 익명화되면 다음 값들이 null로 설정됩니다:

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

isDeleted 및 isDeletedUser는 true로 설정됩니다.

렌더링 시 댓글 위젯은 사용자의 이름에 DELETED_USER_PLACEHOLDER (기본값: "[deleted]")을, 댓글에는 DELETED_CONTENT_PLACEHOLDER를 사용합니다. 이는 Widget Customization UI에서 사용자화할 수 있습니다.

예제

SSOUser 제거 cURL 예제

Copy

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

SSOUser 제거 요청 구조

Copy

enum SSOUserCommentDeleteMode {
    Remove = 0, // 기본값
    Anonymize = 1
}
interface SSOUsersDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** 사용자의 댓글도 삭제하려면 이를 true로 설정할 수 있습니다. 이 경우 크레딧 비용이 두 배가 됩니다. **/
    deleteComments?: 'true' | 'false'
    /** 사용자의 댓글을 어떻게 처리할지 결정하려면 원하는 값으로 설정할 수 있습니다. **/
    commentDeleteMode?: SSOUserCommentDeleteMode
}

SSOUser 제거 응답 구조

Copy

interface SSOUsersResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'user-does-not-exist'
    /** 실패 시 포함됩니다. **/
    reason?: string
    user?: SSOUser; // 성공 시 제거된 사용자를 반환합니다.
}

구독 구조

Subscription 객체는 사용자의 구독을 나타냅니다.

Subscription 객체는 사용자가 댓글 위젯의 알림 벨을 클릭하고 "이 페이지 구독"을 클릭할 때 생성됩니다.

구독은 API를 통해서도 생성할 수 있습니다.

Subscription 객체가 있으면 연관된 페이지의 루트에 새 댓글이 남겨질 때 해당 Subscription의 대상인 페이지에 대해 Notification 객체가 생성되고 이메일이 전송됩니다. 이메일 전송은 사용자 유형에 따라 달라집니다. 일반 사용자에게는 optedInNotifications에 따라 결정됩니다. SSO 사용자에게는 optedInSubscriptionNotifications에 따라 결정됩니다. 일부 애플리케이션은 웹에서 접근 가능한 페이지 개념이 없을 수 있으므로, 그런 경우 구독하려는 항목의 id(댓글 위젯에 전달할 urlId와 동일한 값)를 urlId에 설정하면 됩니다.

Subscription 객체의 구조는 다음과 같습니다:

구독 구조

Copy

interface Subscription {
    id: string
    tenantId: string
    /** SSO의 경우, 사용자 id는 `<tenant id>:<user id>` 형식입니다. **/
    userId: string
    anonUserId?: string
    urlId: string
    url?: string
    pageTitle?: string
    createdAt: string // 날짜 문자열
}

GET /api/v1/subscriptions/:id

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

이 경로는 createdAt 기준으로 정렬된 최신순으로 최대 30개의 Subscription 객체를 반환합니다.

userId로 필터링할 수 있습니다. SSO를 사용하는 경우 사용자 ID는 <tenant id>:<user id> 형식입니다.

사용자용 구독 cURL 예제

Copy

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

구독 요청 구조

Copy

interface SubscriptionsGetQueryParams {
    tenantId: string
    API_KEY: string
    /** 레코드를 건너뛰어 페이지네이션합니다. **/
    skip?: number
    /** 사용자로 필터링합니다. **/
    userId?: string
}

구독 응답 구조

Copy

interface SubscriptionsGetResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** 실패 시 포함됩니다. **/
    reason?: string
    subscriptions?: Subscription[]
}

POST /api/v1/subscriptions

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

이 API 엔드포인트는 Subscription을 생성하는 기능을 제공합니다. 사용자는 페이지당 하나의 구독만 가질 수 있다는 점에 유의하세요. 이는 중복되므로, 그리고 동일한 사용자와 동일한 페이지에 대해 둘 이상의 구독을 생성하려고 하면 오류가 발생합니다.

구독을 생성하면, 구독된 urlId의 루트에 새 댓글이 남겨질 때(댓글의 parentId가 null인 경우) Notification 객체가 생성됩니다.

Subscription POST cURL 예제

Copy

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

Subscription POST 요청 구조

Copy

interface SubscriptionPostQueryParams {
    tenantId: string
    API_KEY: string
}

Subscription POST 응답 구조

Copy

interface SubscriptionPostResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'unauthorized' | 'not-found';  
    /** 실패 시 포함됩니다. **/
    reason?: string
}

DELETE /api/v1/subscriptions/:id

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

이 경로는 id로 단일 Subscription 객체를 삭제합니다.

구독 삭제 cURL 예제

Copy

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

구독 삭제 요청 구조

Copy

interface SubscriptionsDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

구독 삭제 응답 구조

Copy

interface SubscriptionDeleteResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** 실패 시 포함됩니다. **/
    reason?: string
}

테넌트 일별 사용량 구조

A TenantDailyUsage 객체는 특정 날짜에 대한 테넌트의 사용량을 나타냅니다. 특정 테넌트가 해당 날짜에 활동이 없었다면 그 날짜에는 TenantDailyUsage 객체가 생성되지 않습니다.

The TenantDailyUsage object is not real time and may be minutes behind actual usage.

TenantDailyUsage 객체의 구조는 다음과 같습니다:

TenantDailyUsage 구조

Copy

export interface TenantDailyUsage {
    yearNumber: number
    monthNumber: number
    dayNumber: number
    commentFetchCount?: number
    commentCreateCount?: number
    conversationCreateCount?: number
    voteCount?: number
    accountCreatedCount?: number
    userMentionSearch?: number
    hashTagSearch?: number
    gifSearchTrending?: number
    gifSearch?: number
    apiCreditsUsed?: number
    createdAt: string
    billed: boolean
    /** 청구에서 무시됩니다. **/
    ignored: boolean
}

GET /api/v1/tenant-daily-usage

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

이 라우트는 연, 월, 일 단위로 테넌트의 사용량을 검색할 수 있게 해줍니다. 최대 365개의 객체를 반환할 수 있으며, 비용은 10개 객체당 1 api credit입니다.

응답 객체는 생성된 날짜순으로 정렬됩니다(가장 오래된 것이 먼저).

TenantDailyUsage 검색 cURL 예제

Copy

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

TenantDailyUsage 요청 구조

Copy

interface TenantDailyUsageQueryParams {
    tenantId: string
    API_KEY: string
    /** UTC 기준입니다. **/
    yearNumber?: number
    /** 0부터 시작합니다. UTC 기준입니다. **/
    monthNumber?: number
    /** 1부터 시작합니다. UTC 기준입니다. **/
    dayNumber?: number
}

TenantDailyUsage 응답 구조

Copy

interface TenantDailyUsageResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** 실패 시 포함됩니다. **/
    reason?: string
    tenantDailyUsages: TenantDailyUsage[]
}

테넌트 구조

Tenant는 FastComments.com의 고객을 정의합니다. 화이트 라벨링 권한이 있는 테넌트는 API를 통해 생성할 수 있습니다. 화이트 라벨 테넌트는 다른 화이트 라벨 테넌트를 생성할 수 없습니다(중첩은 한 단계만 허용됩니다).

다음은 Tenant 객체의 구조입니다:

테넌트 구조

Copy

export enum SiteType {
    Unknown = 0,
    WordPress = 1
}
/** 이는 DomainConfig API로도 처리할 수 있습니다. **/
export interface TenantDomainConfig {
    domain: string
    emailFromName?: string
    emailFromEmail?: string
    createdAt?: string,
    siteType?: FastCommentsSiteType, // 아마 Unknown을 원할 것입니다
    logoSrc?: string, // 원본 이미지 경로
    logoSrc100px?: string, // 썸네일용으로 리사이즈됨
    footerUnsubscribeURL?: string,
    emailHeaders?: Record<string, string>,
    disableUnsubscribeLinks?: boolean,
    dkim?: {
        domainName: string,
        keySelector: string,
        privateKey: string
    }
}
export interface TenantBillingInfo {
    name: string
    address: string
    city: string
    state: string
    zip: string
    country: string
}
export enum TenantPaymentFrequency {
    Monthly = 0,
    Annually = 1
}
export interface Tenant {
    id: string
    name: string
    email?: string
    signUpDate: number; // '레거시' 이유로 number 타입입니다
    packageId?: string | null
    paymentFrequency?: TenantPaymentFrequency
    billingInfoValid?: boolean
    billingHandledExternally?: boolean
    createdBy?: string
    isSetup?: boolean
    domainConfiguration: FastCommentsAPITenantDomainConfig[]
    billingInfo?: FastCommentsAPITenantBillingInfo
    stripeCustomerId?: string
    stripeSubscriptionId?: string
    stripePlanId?: string
    enableProfanityFilter?: boolean
    enableSpamFilter?: boolean
    lastBillingIssueReminderDate?: string
    removeUnverifiedComments?: boolean
    unverifiedCommentsTTLms?: number
    commentsRequireApproval?: boolean
    autoApproveCommentOnVerification?: boolean
    sendProfaneToSpam?: boolean
    /** @readonly - packageId를 기반으로 계산됩니다. **/
    hasFlexPricing?: boolean
    /** @readonly **/
    flexLastBilledAmount?: number
    /** @readonly - packageId를 기반으로 계산됩니다. **/
    hasAuditing?: boolean
    /** 테넌트에 키-값 쌍을 저장하여 쿼리에 사용할 수 있습니다. 키에는 "." 또는 "$"를 포함할 수 없고 길이는 100자를 초과할 수 없습니다. 값은 2k 문자를 초과할 수 없습니다. **/
    meta?: Record<string, string | null>
}

GET /api/v1/tenants/:id

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

이 경로는 ID로 단일 Tenant를 반환합니다.

ID로 Tenant 조회 cURL 예제

Copy

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

Tenant 요청 구조

Copy

interface TenantByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Tenant 응답 구조

Copy

interface TenantByIdResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'unauthorized'
    /** 실패 시 포함됩니다. **/
    reason?: string
    tenant?: Tenant
}

GET /api/v1/tenants

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

이 API는 귀하의 테넌트가 관리하는 테넌트를 반환합니다.

페이지네이션은 skip 쿼리 매개변수로 제공됩니다. 테넌트는 signUpDate 및 id로 정렬되어 100개 단위의 페이지로 반환됩니다.

비용은 반환된 테넌트 수에 따라 결정되며, 반환된 테넌트 10개당 1 credit per 10가 발생합니다.

Tenant cURL 예제

Copy

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

Tenant 객체에 meta 매개변수를 정의하고 일치하는 테넌트를 쿼리할 수 있습니다. 예를 들어, 키가 someKey이고 메타 값이 some-value인 경우, 이 키/값 쌍으로 JSON 객체를 구성한 다음 이를 쿼리 파라미터로 URI 인코딩하여 필터할 수 있습니다:

Tenant Query by Meta cURL 예제

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
    /** 페이지네이션을 위한 건너뛸 테넌트 수. **/
    skip?: number
    /** meta 매개변수로 필터링합니다. **/
    meta?: string
}

Tenant 응답 구조

Copy

interface TenantsResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** 실패 시 포함됩니다. **/
    reason?: string
    tenants?: Tenant[]
}

POST /api/v1/tenants

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

이 라우트는 단일 Tenant를 추가하는 기능을 제공합니다.

Tenant를 생성할 때 다음과 같은 제한이 있습니다:

name은 필수입니다.
domainConfiguration은 필수입니다.
Tenant를 생성할 때 다음 값들은 제공할 수 없습니다:
- hasFlexPricing
- lastBillingIssueReminderDate
- flexLastBilledAmount
signUpDate는 미래 날짜일 수 없습니다.
name은 200 characters를 초과할 수 없습니다.
email은 300 characters를 초과할 수 없습니다.
email은 FastComments.com의 모든 테넌트에서 고유해야 합니다.
부모 테넌트에 유효한 TenantPackage가 정의되어 있지 않으면 테넌트를 생성할 수 없습니다.
- 테넌트가 FastComments.com을 통해 생성된 경우 이는 문제가 되지 않습니다.
패키지에 정의된 maxWhiteLabeledTenants보다 많은 테넌트를 생성할 수 없습니다.
화이트 라벨링이 활성화된 parent tenant의 id인 tenantId 쿼리 파라미터를 반드시 지정해야 합니다.

우리는 몇 가지 파라미터만으로 Tenant를 생성할 수 있습니다:

테넌트 생성 cURL 예제

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

테넌트 생성 요청 구조

Copy

interface TenantPostQueryParams {
    tenantId: string
    API_KEY: string
}

테넌트 생성 응답 구조

Copy

interface TenantPostResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' | 'unexpected-param' | 'sign-up-date-in-future' | 'payment-frequency-invalid' | 'cannot-change-payment-frequency' | 'name-invalid' | 'email-invalid' | 'email-taken' | 'no-package' | 'invalid-package' | 'unauthorized' | 'tenant-limit-reached' | 'cannot-move-tenant' | 'cannot-change-package' | 'invalid-billing-info'
    /** 실패 시 포함됩니다. **/
    reason?: string
    tenant?: Tenant; // 성공 시 생성된 tenant 전체를 반환합니다.
}

PATCH /api/v1/tenants/:id

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

This API endpoint provides the ability to update a Tenant by id.

Updating a Tenant has the following restrictions:

The following values may not be updated:
- hasFlexPricing
- lastBillingIssueReminderDate
- flexLastBilledAmount
- managedByTenantId
The signUpDate may not be in the future.
The name may not be longer than 200 characters.
The email may not be longer than 300 characters.
The email must be unique across all of FastComments.com tenants.
When setting billingInfoValid to true, billingInfo must be provided in the same request.
You may not update the packageId associated with your own tenant.
You may not update the paymentFrequency associated with your own tenant.

Tenant PATCH cURL 예제

Copy

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

Tenant PATCH 요청 구조

Copy

interface TenantPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Tenant PATCH 응답 구조

Copy

interface TenantPatchResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' | 'unexpected-param' | 'sign-up-date-in-future' | 'payment-frequency-invalid' | 'cannot-change-payment-frequency' | 'name-invalid' | 'email-invalid' | 'email-taken' | 'no-package' | 'invalid-package' | 'unauthorized' | 'tenant-limit-reached' | 'cannot-move-tenant' | 'cannot-change-package' | 'invalid-billing-info'; 
    /** 실패 시 포함됩니다. **/
    reason?: string
}

DELETE /api/v1/tenants/:id

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

이 경로는 id로 Tenant 및 연관된 모든 데이터 (사용자, 댓글 등)를 제거합니다.

다음과 같은 테넌트 제거에 대한 제한이 있습니다:

해당 테넌트는 귀하의 것이어야 하거나, 귀하가 관리하는 화이트라벨 테넌트여야 합니다.
쿼리 매개변수 sure는 true로 설정되어 있어야 합니다.

테넌트 제거 cURL 예제

Copy

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

테넌트 삭제 요청 구조

Copy

interface TenantDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

테넌트 삭제 응답 구조

Copy

interface TenantDeleteResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized' | 'unsure'
    /** 실패 시 포함됩니다. **/
    reason?: string
}

테넌트 패키지 구조

The TenantPackage defines package information available to a Tenant. A tenant may have many packages available, but only one in use at a given time.

A Tenant cannot be used for any products until its packageId points to a valid TenantPackage.

There are two types of TenantPackage objects:

Fixed-pricing packages - where hasFlexPricing is false.
Flexible pricing - where hasFlexPricing is true.

In both case limits are defined on the account using the package, however with Flex the tenant is charged a base price plus what they used, defined by the flex* parameters.

A tenant may have multiple tenant packages and have the ability to change the package themselves from the 청구 정보 페이지.

If you will be handling billing for tenants yourselves, you will still need to define a package for each tenant to define their limits. Simply set billingHandledExternally to true on the Tenant and they will not be able to change their billing information, or active package, themselves.

You may not create packages with higher limits than the parent tenant.

The structure for the TenantPackage object is as follows:

TenantPackage 구조

Copy

export interface TenantPackage {
    id: string
    name: string
    tenantId: string
    createdAt: string
    monthlyCostUSD: number
    yearlyCostUSD: number
    monthlyStripePlanId?: string
    yearlyStripePlanId?: string
    maxMonthlyPageLoads: number
    maxMonthlyAPICredits: number
    maxMonthlyComments: number
    maxConcurrentUsers: number
    maxTenantUsers: number
    maxSSOUsers: number
    maxModerators: number
    maxDomains: number
    maxWhiteLabeledTenants: number
    hasWhiteLabeling: boolean
    hasDebranding: boolean
    forWhoText: string
    featureTaglines: string[]
    hasAuditing: boolean
    hasFlexPricing: boolean
    flexPageLoadCostCents?: null
    flexPageLoadUnit?: null
    flexCommentCostCents?: null
    flexCommentUnit?: null
    flexSSOUserCostCents?: null // 일반 SSO 사용자(관리자/모더레이터 권한 없음)당 비용
    flexSSOUserUnit?: null
    flexAPICreditCostCents?: null
    flexAPICreditUnit?: null
    flexModeratorCostCents?: null
    flexModeratorUnit?: null
    flexAdminCostCents?: null
    flexAdminUnit?: null
    flexDomainCostCents?: null
    flexDomainUnit?: null
    flexSSOAdminCostCents?: null // 관리자 권한이 있는 SSO 사용자당 비용 (isAccountOwner 또는 isAdminAdmin 플래그)
    flexSSOAdminUnit?: null
    flexSSOModeratorCostCents?: null // 모더레이터 권한이 있는 SSO 사용자당 비용 (isCommentModeratorAdmin 플래그)
    flexSSOModeratorUnit?: null
    flexMinimumCostCents?: null
}

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

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

이 라우트는 id로 단일 Tenant Package를 반환합니다.

TenantPackage ID별 cURL 예제

Copy

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

TenantPackage 요청 구조

Copy

interface TenantPackageByIdQueryParams {
    tenantId: string
    API_KEY: string
}

TenantPackage 응답 구조

Copy

interface TenantPackageByIdResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** 실패 시 포함됩니다. **/
    reason?: string
    tenantPackage: TenantPackage
}

GET /api/v1/tenant-packages

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

이 API는 페이징을 사용하며, skip 쿼리 매개변수로 제공됩니다. TenantPackages는 100개 단위로 페이지별로 반환되며, createdAt 및 id로 정렬됩니다.

비용은 반환되는 tenant packages 수를 기준으로 하며, 반환되는 tenant packages 10개당 1 credit per 10가 소요됩니다.

TenantPackage cURL 예제

Copy

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

TenantPackage 요청 구조

Copy

interface TenantPackagesRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** 페이지네이션을 위해 건너뛸 tenant packages의 수. **/
    skip?: number
}

TenantPackage 응답 구조

Copy

interface TenantPackagesResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** 실패 시 포함됩니다. **/
    reason?: string
    tenantPackages?: TenantPackage[]
}

POST /api/v1/tenant-packages

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

이 라우트는 단일 TenantPackage를 추가할 수 있는 기능을 제공합니다.

TenantPackage 생성에는 다음과 같은 제한 사항이 있습니다:

다음 매개변수가 필요합니다:
- name
- tenantId
- monthlyCostUSD - null일 수 있습니다.
- yearlyCostUSD - null일 수 있습니다.
- maxMonthlyPageLoads
- maxMonthlyAPICredits
- maxMonthlyComments
- maxConcurrentUsers
- maxTenantUsers
- maxSSOUsers
- maxModerators
- maxDomains
- hasDebranding
- forWhoText
- featureTaglines
- hasFlexPricing - true이면 모든 flex* 매개변수가 필요합니다.
name은 50 characters보다 길 수 없습니다.
각 forWhoText 항목은 200 characters보다 길 수 없습니다.
각 featureTaglines 항목은 100 characters보다 길 수 없습니다.
TenantPackage는 부모 테넌트보다 "작아야" 합니다. 예를 들어 모든 max* 매개변수는 부모 테넌트보다 낮은 값을 가져야 합니다.
화이트 라벨링된 테넌트는 최대 다섯 개의 패키지를 가질 수 있습니다.
화이트 라벨링 접근 권한이 있는 테넌트만 TenantPackage를 생성할 수 있습니다.
자신의 테넌트에는 패키지를 추가할 수 없습니다. :)

다음과 같이 TenantPackage를 생성할 수 있습니다:

TenantPackage 생성 - 이메일 cURL 예제

Copy

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

TenantPackage 생성 요청 구조

Copy

interface TenantPackagePostQueryParams {
    tenantId: string
    API_KEY: string
}

TenantPackage 생성 응답 구조

Copy

interface TenantPackagePostResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' 'white-labeling-not-allowed' | 'name-too-long' | 'for-who-text-too-long' | 'feature-tag-lines-too-long' | 'no-package' | 'invalid-package' | 'unauthorized' | 'child-tenant-too-large' | 'flex-param-missing' | 'unexpected-flex-param' | 'package-limit-reached' | 'flex-param-missing' | 'unexpected-flex-param'
    /** 실패 시 포함됩니다. **/
    reason?: string
    tenantPackage?: TenantPackage; // 성공 시 생성된 전체 테넌트 패키지를 반환합니다.
}

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

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

이 API 엔드포인트는 id로 TenantPackage를 업데이트하는 기능을 제공합니다.

TenantPackage를 업데이트할 때 다음 제한 사항이 적용됩니다:

hasFlexPricing를 true로 설정하는 경우, 같은 요청에서 모든 flex* 매개변수가 필요합니다.
name은 50 characters보다 길 수 없습니다.
각 forWhoText 항목은 200 characters보다 길 수 없습니다.
각 featureTaglines 항목은 100 characters보다 길 수 없습니다.
TenantPackage는 상위 테넌트보다 "작아야" 합니다. 예를 들어, 모든 max* 매개변수는 상위 테넌트보다 낮은 값을 가져야 합니다.
TenantPackage에 연결된 tenantId는 변경할 수 없습니다.

TenantPackage PATCH cURL 예제

Copy

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

TenantPackage PATCH 요청 구조

Copy

interface TenantPackagePatchQueryParams {
    tenantId: string
    API_KEY: string
}

TenantPackage PATCH 응답 구조

Copy

interface TenantPackagePatchResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' | 'white-labeling-not-allowed' | 'name-too-long' | 'for-who-text-too-long' | 'feature-tag-lines-too-long' | 'no-package' | 'invalid-package' | 'unauthorized' | 'child-tenant-too-large' | 'flex-param-missing' | 'unexpected-flex-param' | 'package-limit-reached' | 'flex-param-missing' | 'unexpected-flex-param'; 
    /** 실패 시 포함됩니다. **/
    reason?: string
}

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

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

이 경로는 id로 TenantPackage를 삭제합니다.

사용 중인 TenantPackage(테넌트의 packageId가 해당 패키지를 가리키는 경우)는 삭제할 수 없습니다. 먼저 Tenant를 업데이트하세요.

TenantPackage 제거 cURL 예제

Copy

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

TenantPackage 제거 요청 구조

Copy

interface TenantPackageDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

TenantPackage 제거 응답 구조

Copy

interface TenantPackageDeleteResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized' | 'package-in-use'
    /** 실패 시 포함됩니다. **/
    reason?: string
}

테넌트 사용자 구조

The TenantUser defines a User which is managed by a specific tenant. Their account is in complete control of the tenant they are associated with, and their account can be updated or deleted via the UI or API.

Tenant users can be administrators with all permissions and access to the Tenant, or they can be limited to specific permissions to moderate comments, access API keys, etc.

The structure for the TenantUser object is as follows:

TenantUser 구조

Copy

/** 알림을 위한 설정입니다. **/
export enum UserDigestEmailFrequency {
    Disabled = -1,
    Daily = 0,
    Weekly = 1,
    Monthly = 2
}
export interface TenantUser {
    id: string
    tenantId: string
    username: string
    /** 예를 들어 댓글 작성자의 블로그 링크입니다. **/
    websiteUrl?: string
    email: string
    signUpDate: number
    createdFromUrlId: string
    createdFromTenantId: string
    verified: boolean
    loginCount: number
    optedInNotifications: boolean
    optedInTenantNotifications: boolean
    hideAccountCode: boolean
    avatarSrc?: string
    /** 사용자가 댓글 작성자들로부터의 도움 요청을 받는가? **/
    isHelpRequestAdmin: boolean
    isAccountOwner: boolean
    isAdminAdmin: boolean
    isBillingAdmin: boolean
    isAnalyticsAdmin: boolean
    isCustomizationAdmin: boolean
    isManageDataAdmin: boolean
    isCommentModeratorAdmin: boolean
    isAPIAdmin: boolean
    moderatorIds: string[]
    locale: FastCommentsLocale
    digestEmailFrequency: UserDigestEmailFrequency
    lastLoginDate: string
    displayLabel?: string
    karma?: number
}

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

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

이 경로는 id로 단일 TenantUser를 반환합니다.

ID로 TenantUser 조회 cURL 예제

Copy

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

TenantUser 요청 구조

Copy

interface TenantUserByIdQueryParams {
    tenantId: string
    API_KEY: string
}

TenantUser 응답 구조

Copy

interface TenantUserByIdResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'unauthorized'
    /** 실패 시 포함됩니다. **/
    reason?: string
    tenantUser?: TenantUser
}

GET /api/v1/tenant-users

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

이 API는 페이지네이션을 사용하며, skip 쿼리 매개변수로 제공됩니다. TenantUsers는 100개 단위의 페이지로 반환되며 signUpDate, username 및 id 순으로 정렬됩니다.

비용은 반환되는 tenant users 수를 기준으로 계산되며, 반환되는 tenant users 10명당 1 credit이 소모됩니다.

TenantUser cURL 예제

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
    /** 페이지네이션을 위해 건너뛸 tenant users 수. **/
    skip?: number
}

TenantUser 응답 구조

Copy

interface TenantUsersResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** 실패 시 포함됩니다. **/
    reason?: string
    tenantUsers?: TenantUser[]
}

POST /api/v1/tenant-users

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

이 라우트는 단일 TenantUser를 추가하는 기능을 제공합니다.

TenantUser를 생성할 때 다음과 같은 제한이 있습니다:

username은 필수입니다.
email은 필수입니다.
signUpDate는 미래일 수 없습니다.
locale은 Supported Locales 목록에 있어야 합니다.
username은 FastComments.com 전체에서 고유해야 합니다. 문제가 발생하면 대신 SSO 사용을 권장합니다.
email은 FastComments.com 전체에서 고유해야 합니다. 문제가 발생하면 대신 SSO 사용을 권장합니다.
패키지에 정의된 maxTenantUsers보다 더 많은 테넌트 사용자를 생성할 수 없습니다.

다음과 같이 TenantUser를 생성할 수 있습니다

TenantUser 생성 cURL 예제

Copy

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

TenantUser 생성 요청 구조

Copy

interface TenantUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

TenantUser 생성 응답 구조

Copy

interface TenantUserPostResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'username-required' | 'email-required' | 'sign-up-date-in-future' | 'unsupported-locale' | 'unauthorized' | 'username-taken' | 'email-taken' | 'tenant-user-limit-reached'
    /** 실패 시 포함됩니다. **/
    reason?: string
    tenantUser?: TenantUser; // 성공 시 생성된 전체 테넌트 사용자를 반환합니다.
}

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

이 경로는 단일 TenantUser에게 로그인 링크를 보낼 수 있는 기능을 제공합니다.

사용자들을 일괄 생성할 때 그들에게 FastComments.com에 로그인하는 방법을 안내할 필요가 없을 때 유용합니다. 이는 만료 기간이 30 days인 "매직 링크"를 전송합니다.

TenantUser에게 로그인 링크를 보내기 위해 다음과 같은 제한이 있습니다:

TenantUser는 이미 존재해야 합니다.
TenantUser가 속한 Tenant를 관리할 수 있는 권한이 있어야 합니다.

다음과 같이 TenantUser에게 로그인 링크를 보낼 수 있습니다:

TenantUser 로그인 링크 cURL 예제

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 at TenantName is inviting you to be a moderator... 같은 이메일을 보냅니다.

TenantUser 로그인 링크 요청 구조

Copy

interface TenantUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

TenantUser 로그인 링크 응답 구조

Copy

interface TenantUserPostResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'not-found'
    /** 실패 시 포함됩니다. **/
    reason?: string
}

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

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

이 라우트는 단일 TenantUser를 업데이트하는 기능을 제공합니다.

TenantUser 업데이트에는 다음과 같은 제한이 있습니다:

signUpDate는 미래일 수 없습니다.
locale는 지원되는 로케일 목록에 있어야 합니다.
username은 FastComments.com 전체에서 고유해야 합니다. 문제가 되는 경우 대신 SSO 사용을 권장합니다.
email은 FastComments.com 전체에서 고유해야 합니다. 문제가 되는 경우 대신 SSO 사용을 권장합니다.
사용자의 tenantId는 업데이트할 수 없습니다.

다음과 같이 TenantUser를 생성할 수 있습니다

TenantUser 업데이트 cURL 예제

Copy

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

TenantUser 업데이트 요청 구조

Copy

interface TenantUserPatchQueryParams {
    tenantId: string
    API_KEY: string
    /** email 또는 username이 변경될 때, 이를 true로 설정하면 사용자의 댓글도 함께 업데이트할 수 있습니다. 이 경우 크레딧 비용이 두 배가 됩니다. **/
    updateComments: 'true' | 'false'
}

TenantUser 업데이트 응답 구조

Copy

interface TenantUserPatchResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'sign-up-date-in-future' | 'unsupported-locale' | 'unauthorized' | 'username-taken' | 'email-taken' | 'unauthorized' | 'no-package' | 'invalid-package' | 'tenant-user-limit-reached' | 'user-does-not-exist'
    /** 실패 시 포함됩니다. **/
    reason?: string
}

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

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

이 경로는 id로 TenantUser를 제거합니다.

사용자의 댓글 삭제는 deleteComments 쿼리 매개변수를 통해 가능합니다. 이것이 true인 경우:

사용자의 모든 댓글이 실시간으로 삭제됩니다.
모든 child (이제는 고아가 된) 댓글은 각 댓글에 연결된 페이지 구성에 따라 삭제되거나 익명처리됩니다. 예를 들어 스레드 삭제 모드가 "anonymize"인 경우 답글은 남아 있고 사용자의 댓글만 익명화됩니다. 이는 commentDeleteMode가 Remove일 때만 적용됩니다(기본값).
creditsCost는 2가 됩니다.

Anonymized Comments

사용자의 댓글을 유지하되 단순히 익명화하려면 commentDeleteMode=1로 설정하십시오.

사용자의 댓글이 익명화되면 다음 값들이 null로 설정됩니다:

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

isDeleted 및 isDeletedUser는 true로 설정됩니다.

렌더링 시 댓글 위젯은 사용자 이름에 DELETED_USER_PLACEHOLDER (기본값: "[deleted]")를, 댓글에는 DELETED_CONTENT_PLACEHOLDER를 사용합니다. 이는 위젯 사용자 지정 UI를 통해 변경할 수 있습니다.

Examples

TenantUser 제거 cURL 예제

Copy

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

TenantUser 제거 요청 구조

Copy

enum TenantUserCommentDeleteMode {
    Remove = 0, // 기본값
    Anonymize = 1
}
interface TenantUserDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** 사용자의 댓글도 삭제하려면 이것을 true로 설정할 수 있습니다. 이 경우 크레딧 비용이 두 배가 됩니다. **/
    deleteComments?: 'true' | 'false'
    /** 사용자 댓글을 어떻게 처리할지 결정하기 위해 원하는 값으로 설정할 수 있습니다. **/
    commentDeleteMode?: TenantUserCommentDeleteMode
}

TenantUser 제거 응답 구조

Copy

interface TenantUserDeleteResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized'
    /** 실패 시 포함됩니다. **/
    reason?: string
}

사용자 구조

User는 모든 사용자들의 공통 분모를 나타내는 객체입니다.

FastComments에서는 사용자에 대한 여러 가지 다른 사용 사례가 있다는 점을 염두에 두세요:

Secure SSO
Simple SSO
Tenant Users (For example: Administrators)
Commenters

이 API는 Commenters 및 Simple SSO를 통해 생성된 사용자들을 위한 것입니다. 기본적으로 사이트를 통해 생성된 모든 사용자는 이 API로 접근할 수 있습니다. Tenant Users도 이렇게 가져올 수 있지만, /tenant-users/ API와 상호작용하면 더 많은 정보를 얻을 수 있습니다.

Secure SSO의 경우에는 /sso-users/ API를 사용하세요.

이 유형의 사용자는 업데이트할 수 없습니다. 이들은 귀하의 사이트를 통해 계정을 생성했기 때문에 일부 읽기 전용 기본 액세스만 제공되며 변경은 할 수 없습니다. 이런 흐름을 원하시면 Secure SSO를 설정해야 합니다.

User 객체의 구조는 다음과 같습니다:

User 구조

Copy

export interface User {
    /** 이것은 댓글 객체의 userId로도 사용되는 id입니다. **/
    id: string
    username: string
    /** 예: 댓글 작성자의 블로그 링크입니다. **/
    websiteUrl?: string
    email: string
    signUpDate: number
    createdFromUrlId: string
    createdFromTenantId: string
    avatarSrc?: string
    locale: FastCommentsLocale
    displayLabel?: string
    karma?: number
}

GET /api/v1/users/:id

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

이 라우트는 id로 단일 User를 반환합니다.

ID로 User 조회 cURL 예제

Copy

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

User 요청 구조

Copy

interface UserByIdQueryParams {
    tenantId: string
    API_KEY: string
}

User 응답 구조

Copy

interface UserByIdResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'unauthorized'
    /** 실패 시 포함됩니다. **/
    reason?: string
    user?: User
}

투표 구조

Vote 객체는 사용자가 남긴 투표를 나타냅니다.

댓글과 투표 간의 관계는 commentId로 정의됩니다.

Vote 객체의 구조는 다음과 같습니다:

Vote 구조

Copy

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

GET /api/v1/votes

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

투표는 urlId로 가져와야 합니다.

투표 유형

투표에는 세 가지 유형이 있습니다:

인증된 투표(Authenticated Votes)는 해당 댓글에 적용됩니다. 이 API를 통해 생성할 수 있습니다.
인증된 투표(Authenticated Votes) 중 검증 대기(pending) 상태인 투표는 아직 댓글에 적용되지 않았습니다. 사용자가 FastComments.com의 login to vote 메커니즘을 사용할 때 생성됩니다.
익명 투표(Anonymous Votes)는 해당 댓글에 적용됩니다. 익명 댓글 작성과 함께 생성됩니다.

혼동을 줄이기 위해 API는 이를 별도의 목록으로 반환합니다.

Votes cURL 예제

Copy

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

Votes 요청 구조

Copy

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

Votes 응답 구조

Copy

interface VotesResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id'
    /** 실패 시 포함됩니다. **/
    reason?: string
    /** 권한이 부여되고 검증된 투표로, 해당 댓글에 적용됩니다. **/
    appliedAuthorizedVotes: Vote[]
    /** 익명 투표로, 해당 댓글에 적용됩니다. **/
    appliedAnonymousVotes: Vote[]
    /** 검증 대기 중인 투표로, 아직 해당 댓글에 적용되지 않았습니다. **/
    pendingVotes: Vote[]
}

익명 투표 참고

이 API를 통해 생성된 익명 투표는 appliedAuthorizedVotes 목록에 나타납니다. API 키로 API를 통해 생성되었기 때문에 권한이 부여된 것으로 간주됩니다.

appliedAnonymousVotes 구조는 이메일, API 키 등이 없이 생성된 투표에 대한 것입니다.

GET /api/v1/votes/for-user

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

지정된 urlId에 대해 사용자가 남긴 투표를 가져올 수 있습니다. userId는 FastComments.com의 사용자 또는 SSO User가 될 수 있습니다.

이는 사용자가 댓글에 투표했는지 보여주려는 경우에 유용합니다. 댓글을 가져올 때 동일한 urlId로 사용자에 대해 이 API를 함께 호출하면 됩니다.

익명 투표를 사용하는 경우 대신 anonUserId를 전달하세요.

사용자별 투표 cURL 예제

Copy

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

익명 사용자 투표 cURL 예제

Copy

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

익명 투표는 appliedAuthorizedVotes 목록에 표시됩니다. 이들은 API 키로 API를 통해 생성되었기 때문에 권한이 있는 것으로 간주됩니다.

사용자별 투표 요청 구조

Copy

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

사용자별 투표 응답 구조

Copy

interface VotesForUserResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'invalid-user-id'
    /** 실패 시 포함됩니다. **/
    reason?: string
    /** 권한이 확인된(검증된) 투표로, 해당 댓글에 적용됩니다. **/
    appliedAuthorizedVotes: Vote[]
    /** 검증 대기 중인 투표로, 아직 해당 댓글에 적용되지 않았습니다. **/
    pendingVotes: Vote[]
}

POST /api/v1/votes

Resource: Vote as POST /api/v1/votes Credit Cost: 1

이 경로는 단일 권한 있는 Vote를 추가할 수 있는 기능을 제공합니다. 투표는 up (+1) 또는 down (-1)일 수 있습니다.

투표 생성 cURL 예제

Copy

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

익명 투표 생성 cURL 예제

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/votes?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-randomly-generated-identifier&commentId=comment-id&direction=up' \
  --header 'Content-Type: application/json'

투표 생성 요청 구조

Copy

interface VotePostQueryParams {
    tenantId: string
    API_KEY: string
    userId?: string
    anonUserId?: string
    commentId: string
    direction: 'up' | 'down'
}

투표 생성 응답 구조

Copy

interface VotePostResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-user-id' | 'invalid-user-id' | 'invalid-comment-id' | 'invalid-direction' | 'duplicate' | 'voting-disabled'
    /** 실패 시 포함됩니다. **/
    reason?: string
    voteId?: string
}

익명 투표 생성

익명 투표는 쿼리 매개변수에서 userId 대신 anonUserId를 설정하여 생성할 수 있습니다.

이 id는 어느 곳의 사용자 객체와 일치할 필요가 없습니다(따라서 익명입니다). 이것은 단순히 식별자 세션을 위한 것이며, 같은 세션에서 다시 투표를 가져와 댓글에 투표가 되었는지 확인할 수 있습니다.

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

기타 참고

이 API는 테넌트 수준 설정을 따릅니다. 예를 들어 특정 페이지에 대해 투표를 비활성화하고 API를 통해 투표를 생성하려고 하면, voting-disabled 오류 코드로 실패합니다.
이 API는 기본적으로 라이브 상태입니다.
이 API는 해당 Comment의 votes를 업데이트합니다.

DELETE /api/v1/votes/:id

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

이 라우트는 단일 Vote를 삭제할 수 있는 기능을 제공합니다.

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'

Vote 삭제 요청 구조

Copy

interface VoteDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Vote 삭제 응답 구조

Copy

interface VoteDeleteResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id'
    /** 실패 시 포함됩니다. **/
    reason?: string
}

Notes:

이 API는 테넌트 수준 설정을 따릅니다. 예를 들어 특정 페이지에서 투표를 비활성화한 상태에서 API를 통해 투표를 생성하려고 하면 오류 코드 voting-disabled로 실패합니다.
이 API는 기본적으로 라이브 상태입니다.
이 API는 해당 Comment의 votes를 업데이트합니다.

도메인 구성 구조

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

The structure for the DomainConfig object is as follows:

도메인 구성 구조

Copy

interface DomainConfig {
    /** 도메인입니다. URL이 아니라 "fastcomments.com" 또는 "www.example.com" 같은 형식입니다. 서브도메인으로 제한하려면 서브도메인을 포함할 수 있습니다. 최대 1000자. **/
    domain: string
    /** 이메일 발송 시 사용되는 발신자 이름(From-Name). **/
    emailFromName?: string
    /** 이메일 발송 시 사용되는 발신자 이메일(From-Email). 이 속성에 사용된 도메인으로 mail.fastcomments.com이 이메일을 보낼 수 있도록 SPF가 설정되어 있는지 확인하세요. **/
    emailFromEmail?: string
    /** 읽기 전용. 객체가 생성된 시각. **/
    createdAt: string
    /** 이 도메인과 관련된 로고. 이메일에 사용됩니다. HTTPS를 사용하세요. **/
    logoSrc?: string
    /** 이 도메인과 관련된 더 작은 로고. HTTPS를 사용하세요. **/
    logoSrc100px?: string
    /** SSO 전용. 전송되는 모든 이메일의 푸터에 사용되는 URL입니다. "[userId]" 변수를 지원합니다. **/
    footerUnsubscribeURL?: string
    /** SSO 전용. 전송되는 모든 이메일에 사용되는 헤더입니다. 예를 들어 배달 개선을 위해 구독취소 관련 헤더를 설정할 때 유용합니다. 이 레코드의 List-Unsubscribe 항목이 존재하는 경우 "[userId]" 변수를 지원합니다. **/
    emailHeaders?: Record<string, string>
    /** 모든 구독취소 링크를 비활성화합니다. 권장되지 않으며, 배달률에 악영향을 줄 수 있습니다. **/
    disableUnsubscribeLinks?: boolean
    /** DKIM 구성. **/
    dkim?: DomainConfigDKIM
}

DKIM 구성 구조

Copy

interface DomainConfigDKIM {
    /** DKIM 레코드에 사용되는 도메인 이름. **/
    domainName: string
    /** 사용될 DKIM 키 셀렉터. **/
    keySelector: string
    /** 개인 키입니다. -----BEGIN PRIVATE KEY-----로 시작하고 -----END PRIVATE KEY-----로 끝나야 합니다. **/
    privateKey: string
}

인증을 위해

도메인 구성은 귀하의 계정에 대해 어떤 사이트들이 FastComments 위젯을 호스팅할 수 있는지를 결정하는 데 사용됩니다. 이는 기본적인 형태의 인증이며, 도메인 구성을 추가하거나 제거하면 운영 환경에서 FastComments 설치의 가용성에 영향을 줄 수 있습니다.

현재 사용 중인 도메인에 대해 해당 도메인의 Domain Config에서 domain 속성을 의도적으로 비활성화하지 않는 한 제거하거나 업데이트하지 마십시오.

이것은 /auth/my-account/configure-domains에서 도메인을 제거하는 것과 동일한 동작을 합니다.

또한 My Domains UI에서 도메인을 제거하면 이 UI를 통해 추가되었을 수 있는 해당 도메인에 대한 모든 구성도 제거된다는 점에 유의하십시오.

이메일 사용자화

이메일 푸터의 구독취소 링크 및 많은 이메일 클라이언트가 제공하는 원클릭 구독취소 기능은 각각 footerUnsubscribeURL과 emailHeaders를 정의하여 이 API를 통해 구성할 수 있습니다.

DKIM

DKIM DNS 레코드를 정의한 후, 위에서 정의한 구조를 사용하여 도메인 구성에 DKIM 구성을 업데이트하면 됩니다.

GET /api/v1/domain-configs

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

이 API는 테넌트의 모든 DomainConfig 객체를 가져오는 기능을 제공합니다.

DomainConfig GET cURL 예제

Copy

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

DomainConfig GET 요청 구조

Copy

interface GetDomainConfigsRequestQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig GET 응답 구조

Copy

interface GetDomainConfigsResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** 실패 시 포함됩니다. **/
    reason?: string
    /** 구성들입니다! **/
    configurations: DomainConfig[] | null
}

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

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

개별 DomainConfig는 해당 domain으로 가져올 수 있습니다.

도메인별 Domain Config cURL 예제

Copy

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

도메인별 Domain Config 요청 구조

Copy

interface DomainConfigsByDomainRequestQueryParams {
    tenantId: string
    API_KEY: string
}

도메인별 Domain Config 응답 구조

Copy

interface DomainConfigResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'internal' | 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'missing-domain' | 'update-would-create-duplicate' | 'domain-does-not-exist'
    /** 실패 시 포함됩니다. **/
    reason?: string
    configuration?: DomainConfig | null
}

POST /api/v1/domain-configs

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

이 API 엔드포인트는 도메인 구성을 생성하는 기능을 제공합니다.

도메인에 대한 구성을 추가하면 해당 도메인이 FastComments 계정에 대해 인증됩니다.

이 API의 일반적인 사용 사례로는 초기 설정, 여러 도메인을 추가하려는 경우, 또는 이메일 발송을 위한 맞춤 구성 등이 있습니다.

DomainConfig POST cURL 예제

Copy

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

DomainConfig POST 요청 구조

Copy

interface DomainConfigPostQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig POST 응답 구조

Copy

interface DomainConfigPostResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'missing-domain' | 'configuration-exists-for-domain' | 'domain-too-long' | 'domain-invalid';  
    /** 실패 시 포함됩니다. **/
    reason?: string
    /** 생성된 구성입니다. **/
    configuration?: DomainConfig
}

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

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

이 API 엔드포인트는 도메인과 업데이트할 속성만 지정하여 도메인 구성을 업데이트할 수 있는 기능을 제공합니다.

DomainConfig PATCH cURL 예제

Copy

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

DomainConfig PATCH 요청 구조

Copy

interface DomainConfigPatchQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig PATCH 응답 구조

Copy

interface DomainConfigPatchResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'missing-domain' | 'domain-does-not-exist' | 'update-would-create-duplicate' | 'domain-too-long' | 'domain-invalid';  
    /** 실패 시 포함됩니다. **/
    reason?: string
    /** 업데이트된 구성입니다. **/
    configuration?: DomainConfig
}

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

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

이 API 엔드포인트는 도메인 구성을 교체할 수 있는 기능을 제공합니다.

DomainConfig PUT cURL 예제

Copy

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

DomainConfig PUT 요청 구조

Copy

interface DomainConfigPutQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig PUT 응답 구조

Copy

interface DomainConfigPutResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'missing-domain' | 'domain-does-not-exist' | 'update-would-create-duplicate' | 'domain-too-long' | 'domain-invalid';  
    /** 실패 시 포함됩니다. **/
    reason?: string
    /** 업데이트된 구성. **/
    configuration?: DomainConfig
}

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

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

이 경로는 단일 DomainConfig를 id로 제거합니다.

참고: DomainConfig를 제거하면 해당 도메인이 FastComments 사용 권한을 상실합니다.
참고: UI를 통해 도메인을 다시 추가하면 객체가 재생성됩니다(단 domain만 채워집니다).

DomainConfig 제거 cURL 예제

Copy

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

DomainConfig 제거 요청 구조

Copy

interface DomainConfigRequestQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig 제거 응답 구조

Copy

interface DomainConfigDeleteResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-domain' | 'domain-config-does-not-exist'
    /** 실패 시 포함됩니다. **/
    reason?: string
}

질문 구성 구조

FastComments는 질문을 구성하고 그 결과를 집계하는 방법을 제공합니다. 질문의 예(이하 QuestionConfig라고 함)는 별점, 슬라이더, 또는 NPS 질문(type에 의해 결정될 수 있음)이 될 수 있습니다.

질문 데이터는 개별적으로, 함께, 시간 경과에 따라, 전체적으로, 페이지별로 등으로 집계할 수 있습니다.

이 프레임워크는 클라이언트 측 위젯(이 API 앞에 서버를 두는 방식), 관리자 대시보드 및 리포팅 도구를 구축하는 데 필요한 모든 기능을 제공합니다.

먼저 QuestionConfig를 정의해야 합니다. 구조는 다음과 같습니다:

QuestionConfig 구조

Copy

type QuestionConfigType = 'nps' | 'slider' | 'star' | 'thumbs';
interface QuestionConfig {
    id: string
    tenantId: string
    name: string
    question: string
    helpText?: string
    createdAt: string
    createdBy: string
    /** 읽기 전용 - 각 새 응답마다 증가합니다. **/
    usedCount: number
    /** 구성이 마지막으로 사용(결과가 남겨진)된 시점의 날짜 문자열입니다. **/
    lastUsed?: string
    type: QuestionConfigType
    numStars?: number
    min?: number
    max?: number
    defaultValue?: number
    labelNegative?: string
    labelPositive?: string
    subQuestionIds?: string[]
    alwaysShowSubQuestions?: boolean
    reportingOrder: number
}

GET /api/v1/question-configs

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

이 경로는 한 번에 페이징된 최대 100개의 QuestionConfig 객체를 반환합니다. 비용은 100개당 1입니다. 그들은 질문 텍스트 오름차순(question 필드)으로 정렬됩니다.

QuestionConfig 예제

Copy

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

QuestionConfig 요청 구조

Copy

interface QuestionConfigRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
    /** 페이징을 위해 사용합니다. 0부터 시작합니다. **/
    skip?: number
}

QuestionConfig 응답 구조

Copy

interface QuestionConfigByIdResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** 실패 시 포함됩니다. **/
    reason?: string
    questionConfigs: QuestionConfig[]
}

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

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

이 경로는 id로 단일 QuestionConfig를 반환합니다.

QuestionConfig ID로 cURL 예제

Copy

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

QuestionConfig 요청 구조

Copy

interface QuestionConfigRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionConfig 응답 구조

Copy

interface QuestionConfigByIdResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** 실패 시 포함됩니다. **/
    reason?: string
    questionConfig?: QuestionConfig
}

POST /api/v1/question-configs

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

이 API 엔드포인트는 QuestionConfig를 생성하는 기능을 제공합니다.

QuestionConfig POST cURL 예제

Copy

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

QuestionConfig POST 요청 구조

Copy

interface QuestionConfigPostQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionConfig POST 응답 구조

Copy

interface QuestionConfigPostResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input';  
    /** 실패 시 포함됩니다. **/
    reason?: string
    /** 생성된 객체. **/
    questionConfig?: QuestionConfig
}

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

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

이 경로는 단일 QuestionConfig를 업데이트하는 기능을 제공합니다.

다음 구조는 변경 가능한 모든 값을 나타냅니다:

QuestionConfig 구조

Copy

interface QuestionConfigPatchBody {
    name?: string
    question?: string
    helpText?: string
    /** 주의: type을 변경하면 min/max가 다를 경우 보고에 영향을 줄 수 있습니다. **/
    type?: QuestionConfigType
    numStars?: number
    min?: number
    max?: number
    defaultValue?: number
    labelNegative?: string
    labelPositive?: string
    subQuestionIds?: string[]
    alwaysShowSubQuestions?: boolean
    reportingOrder?: number
}

QuestionConfig 업데이트 cURL 예제

Copy

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

QuestionConfig 업데이트 요청 구조

Copy

interface QuestionConfigPatchQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionConfig 업데이트 응답 구조

Copy

interface QuestionConfigPatchResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'unauthorized' | 'missing-api-key' | 'missing-id' | 'not-found' | 'empty-request' | 'invalid-input'
    /** 실패 시 포함됩니다. **/
    reason?: string
}

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

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

이 경로는 id로 QuestionConfig를 제거합니다.

이 작업은 모든 해당 질문 결과를 삭제합니다(댓글은 삭제되지 않습니다). 이것은 높은 크레딧 비용의 일부입니다.

QuestionConfig 제거 cURL 예제

Copy

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

QuestionConfig 제거 요청 구조

Copy

interface QuestionConfigDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionConfig 제거 응답 구조

Copy

interface QuestionConfigResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** 실패 시 포함됩니다. **/
    reason?: string
}

질문 결과 구조

질문에 대한 결과를 저장하려면 QuestionResult를 생성합니다. 그런 다음 질문 결과를 집계할 수 있고, 또한 보고 목적을 위해 댓글에 연결할 수도 있습니다.

QuestionResult 구조

Copy

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

GET /api/v1/question-results

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

이 라우트는 한 번에 최대 1000개의 QuestionResults 객체를 페이지네이션된 형태로 반환합니다. 비용은 100개당 1입니다. 결과는 createdAt 기준 오름차순으로 정렬됩니다. 다양한 매개변수로 필터링할 수 있습니다.

QuestionResults 예시

Copy

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

QuestionResults 요청 구조

Copy

interface QuestionResultsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** 페이지네이션용. 0부터 시작합니다. **/
    skip?: number
    /** 페이지네이션용. **/
    limit?: number
    /** 특정 페이지의 결과를 가져옵니다. **/
    urlId?: string
    /** 특정 사용자의 결과를 가져옵니다. **/
    userId?: string
    startDate?: string | number
    questionId?: string | string[]
}

QuestionResults 응답 구조

Copy

interface QuestionResultsResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** 실패 시 포함됩니다. **/
    reason?: string
    questionResults: QuestionResults[]
}

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

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

이 경로는 id로 단일 QuestionResult를 반환합니다.

QuestionResult ID별 cURL 예제

Copy

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

QuestionResult 요청 구조

Copy

interface QuestionResultRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionResult 응답 구조

Copy

interface QuestionResultByIdResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** 실패 시 포함됩니다. **/
    reason?: string
    questionResult?: QuestionResult
}

POST /api/v1/question-results

Resource: QuestionResult as POST /api/v1/question-results Credit Cost: 1

이 API 엔드포인트는 QuestionResult를 생성할 수 있는 기능을 제공합니다.

QuestionResult POST cURL 예제

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/question-results?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "urlId": "some-page-id",
    "anonUserId": 'anon-0',
    "userId": 'user-0',
    "value": 10,
    "questionId": "some-question-id",
    "meta": [
        {
            name: "example",
            values: ["value-1", "value-2"]
        }
    ]
}'

QuestionResult POST 요청 구조

Copy

interface QuestionResultPostQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionResult POST 응답 구조

Copy

interface QuestionResultPostResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input';  
    /** 실패 시 포함됩니다. **/
    reason?: string
    /** 생성된 객체. **/
    questionResult?: QuestionResult
}

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

Resource: QuestionResult as PATCH /api/v1/question-results/:id Credit Cost: 1

이 경로는 단일 QuestionResult를 업데이트할 수 있는 기능을 제공합니다.

다음 구조는 변경할 수 있는 모든 값을 나타냅니다:

QuestionResult 구조

Copy

interface QuestionResultPatchBody {
    urlId?: string
    anonUserId?: string
    userId?: string
    value?: string
    commentId?: string
    questionId?: string
    meta?: QuestionResultMeta[]
}

QuestionResult 업데이트 cURL 예제

Copy

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

QuestionResult 업데이트 요청 구조

Copy

interface QuestionResultPatchQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionResult 업데이트 응답 구조

Copy

interface QuestionResultPatchResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'unauthorized' | 'missing-api-key' | 'missing-id' | 'not-found' | 'empty-request' | 'invalid-input'
    /** 실패 시 포함됩니다. **/
    reason?: string
}

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

Resource: QuestionResult as DELETE /api/v1/question-results/:id Credit Cost: 1

이 경로는 id로 QuestionResult를 삭제합니다.

QuestionResult 제거 cURL 예제

Copy

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

QuestionResult 제거 요청 구조

Copy

interface QuestionResultDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionResult 제거 응답 구조

Copy

interface QuestionResultResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** 실패 시 포함됩니다. **/
    reason?: string
}

GET /api/v1/question-results-aggregate

Resource: QuestionResultsAggregate as GET /api/v1/question-results-aggregate Credit Cost: 2

여기서 결과의 집계가 수행됩니다.

The aggregation response structure is as follows:

QuestionResultsAggregationResult 구조

Copy

interface QuestionResultDataPoint {
    /** 현재 데이터 포인트(날짜 버킷 또는 페이지)에 대해 값별 발생 횟수를 저장한 맵. **/
    v: Map<ValueAsString, number>
    total: number
}
interface QuestionResultsAggregationResult {
    /** 참고 - timeBucket이 지정되지 않으면 null입니다. **/
    dataByDateBucket?: Map<DateString, QuestionResultDataPoint>
    dataByUrlId?: Map<URLIdString, QuestionResultDataPoint>
    countsByValue?: Map<ValueAsString, number>
    /** 집계된 결과의 총 수입니다. **/
    total: number
    /** 계산된 가중 평균입니다. 보통 소수점 둘째 자리 또는 그 이하입니다. **/
    average: number
    /** 데이터가 캐시에서 제공될 수 있으므로 이 데이터가 계산된 시점을 나타내는 날짜 문자열입니다. **/
    createdAt: string
}

Here are the query parameters available for aggregation:

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
}

Here's an example request:

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'

Example response:

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
}

Performance Notes

For a cache miss aggregations generally take five seconds per million results.
Otherwise, requests are constant-time.

Caching and Cost Notes

When forceRecalculate is specified the cost is always 10, instead of the normal 2.
If the cache expires and data is recalculated, the cost is still a constant 2 if forceRecalculate is not specified. The cache expires based on the data set size aggregated (can vary between 30 seconds and 5 minutes).
This is to incentivize using the cache.

GET /api/v1/question-results-aggregate/combine/comments

Resource: QuestionResultsCombinedWithComments as GET /api/v1/question-results-aggregate/combine/comments Credit Cost: 2

결과와 댓글을 결합하는 기능이 제공되는 엔드포인트입니다. 예를 들어 제품에 대한 "최근 긍정 및 부정 댓글" 차트를 만드는 데 유용합니다.

값의 범위(포함), 하나 이상의 질문, 그리고 시작 날짜(포함)로 검색할 수 있습니다.

응답 구조는 다음과 같습니다:

QuestionResultsCombinedWithCommentsResponse 구조

Copy

interface SimpleComment {
    id: string
    commenterName: string
    userId?: string
    date: string
    commentHTML: string
}
interface SimpleQuestionResult {
    id: string
    value: number
}
interface CommentAndResult {
    comment: SimpleComment
    result: SimpleQuestionResult
}
interface QuestionResultsCombinedWithCommentsResponse {
    /** 이 데이터가 계산된 시점을 나타내는 날짜 문자열입니다(캐시에서 제공될 수 있음). **/
    createdAt: string
    results: CommentAndResult[]
}

다음은 집계를 위한 쿼리 매개변수입니다:

QuestionResultsCombineComments 요청 구조

Copy

interface QuestionResultsAggregateRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** 하나 이상의 질문에 대해 결과를 집계할 수 있습니다. **/
    questionId: string | string[]
    startDate?: string | number
    urlId?: string
    minValue: number
    maxValue: number
    limit?: number
    forceRecalculate?: boolean
}

다음은 예시 요청입니다:

QuestionResultsCombineComments 예제

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/question-results-aggregation/combine/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&questionId=some-question-id&minValue=5&maxValue=10'

다음은 예시 응답입니다:

QuestionResultsCombineComments 응답 예제

Copy

{
    "createdAt": "2023-08-30T00:00:00.000Z",
    "results": [
        {
            "comment": {
                "id": "some-id",
                "commentHTML": "test-2",
                "commenterName": "Test",
                "date": "2023-08-30T00:00:00.000Z",
                "userId": "some-user-id"
            },
            "result": {
                "id": "some-id",
                "value": 10
            }
        },
        {
            "comment": {
                "id": "some-id",
                "commentHTML": "test-0",
                "commenterName": "Some Name",
                "date": "2023-08-30T00:00:00.000Z",
                "userId": "some-user-id"
            },
            "result": {
                "id": "some-id",
                "value": 5
            }
        }
    ]
}

QuestionResultsCombineComments 응답 구조

Copy

interface QuestionResultsCombineCommentsResponse {
    status: 'success' | 'failed'
    /** 실패 시 포함됩니다. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** 실패 시 포함됩니다. **/
    reason?: string
    data: QuestionResultsCombinedWithCommentsResponse
}

캐싱 및 비용 관련 주의사항

forceRecalculate가 지정된 경우 비용은 일반적인 2 대신 항상 10입니다.
캐시가 만료되어 데이터가 재계산되는 경우에도, forceRecalculate가 지정되지 않았다면 비용은 여전히 고정된 2입니다.
이는 캐시 사용을 장려하기 위한 조치입니다.

사용자 배지 구조

UserBadge는 FastComments 시스템에서 사용자에게 할당된 배지를 나타내는 객체입니다.

배지는 활동(예: 댓글 수, 응답 시간, 베테랑 상태)에 따라 자동으로 사용자에게 할당되거나 사이트 관리자가 수동으로 할당할 수 있습니다.

The structure for the UserBadge object is as follows:

UserBadge 구조

Copy

export interface UserBadge {
    /** 이 사용자 배지 할당의 고유 식별자 */
    id: string
    /** 이 배지가 할당된 사용자의 ID */
    userId: string
    /** 테넌트의 배지 카탈로그에 있는 배지 정의의 ID */
    badgeId: string
    /** 이 배지를 생성/할당한 테넌트의 ID */
    fromTenantId: string
    /** 이 배지가 생성된 시각 (에포크 이후 밀리초) */
    createdAt?: number
    /** 사용자가 이 배지를 받은 시각 (에포크 이후 밀리초) */
    receivedAt?: number
    /** 
     * 배지 유형: 
     * 0=CommentCount, 1=CommentUpVotes, 2=CommentReplies, 3=CommentsPinned, 
     * 4=Veteran, 5=NightOwl, 6=FastReplyTime, 7=ModeratorCommentsDeleted,
     * 8=ModeratorCommentsApproved, 9=ModeratorCommentsUnapproved, 10=ModeratorCommentsReviewed,
     * 11=ModeratorCommentsMarkedSpam, 12=ModeratorCommentsMarkedNotSpam, 13=RepliedToSpecificPage,
     * 14=Manual
     */
    type: number
    /** 임계값 기반 배지의 임계값 */
    threshold?: number
    /** 배지의 이름/레이블 */
    name?: string
    /** 배지에 대한 자세한 설명 */
    description?: string
    /** 배지에 표시되는 텍스트 */
    displayLabel?: string
    /** 배지에 표시되는 이미지의 URL */
    displaySrc?: string
    /** 배지의 배경색 (헥스 코드) */
    backgroundColor?: string
    /** 배지의 테두리 색상 (헥스 코드) */
    borderColor?: string
    /** 배지의 텍스트 색상 (헥스 코드) */
    textColor?: string
    /** 스타일링을 위한 추가 CSS 클래스 */
    cssClass?: string
    /** 베테랑 배지의 경우 시간 임계값(밀리초) */
    veteranUserThresholdMillis?: number
    /** 이 배지가 사용자의 댓글에 표시되는지 여부 */
    displayedOnComments: boolean
    /** 배지의 표시 순서 */
    order?: number
}

---

GET /api/v1/user-badges

이 엔드포인트를 사용하면 다양한 기준으로 사용자 배지를 가져올 수 있습니다.

Example Request:

GET 요청 예시

Copy

Run

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

You can add various query parameters to filter the results:

userId - 특정 사용자의 배지를 가져옵니다
badgeId - 특정 배지의 인스턴스를 가져옵니다
type - 배지 유형별로 필터링 (0=CommentCount, 1=CommentUpVotes, 2=CommentReplies, etc. See UserBadge structure for full list)
displayedOnComments - 배지가 댓글에 표시되는지 여부로 필터링 (true/false)
limit - 반환할 배지의 최대 개수 (기본값 30, 최대 200)
skip - 건너뛸 배지 수 (페이지네이션용)

Example Response:

응답

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

Possible Error Responses:

오류: 누락된 테넌트 ID

Copy

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

오류: 잘못된 limit

Copy

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

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

이 엔드포인트는 고유 ID로 특정 사용자 배지를 가져올 수 있게 합니다.

Example Request:

GET 요청 예제

Copy

Run

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

Example Response:

응답

Copy

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

Possible Error Responses:

오류: 테넌트 ID 누락

Copy

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

오류: 찾을 수 없음

Copy

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

---

POST /api/v1/user-badges

이 엔드포인트를 통해 새로운 사용자 배지 할당을 생성할 수 있습니다.

요청 예제:

POST 요청 예제

Copy

Run

curl -X POST "https://fastcomments.com/api/v1/user-badges?tenantId=demo&API_KEY=DEMO_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
  "userId": "user456",
  "badgeId": "badgeDef789",
  "displayedOnComments": true
}'

요청 본문에는 다음 매개변수가 포함되어야 합니다:

userId (required) - 배지를 할당할 사용자의 ID
badgeId (required) - 할당할 배지의 ID
displayedOnComments (optional) - 배지가 사용자의 댓글에 표시될지 여부 (기본값: true)

중요 참고사항:

배지는 테넌트의 배지 카탈로그에 존재하고 활성화되어 있어야 합니다
배지는 귀하의 테넌트에 속해 있거나 귀하의 사이트에 댓글을 남긴 사용자에게만 할당할 수 있습니다

응답 예제:

응답

Copy

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

가능한 오류 응답:

오류: 테넌트 ID 누락

Copy

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

오류: 사용자 ID 누락

Copy

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

오류: 배지 ID 누락

Copy

{
  "status": "failed",
  "code": "missing-badge-id",
  "reason": "Badge ID (body param: badgeId) is required."
}

오류: 배지 없음

Copy

{
  "status": "failed",
  "code": "badge-not-found",
  "reason": "The badge badgeDef789 was not found or is not enabled."
}

오류: 권한 없는 사용자

Copy

{
  "status": "failed",
  "code": "unauthorized-user",
  "reason": "You can only add badges to users who belong to your tenant or have commented on your site."
}

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

이 엔드포인트는 사용자 배지 할당을 업데이트할 수 있도록 합니다.

현재 업데이트할 수 있는 유일한 속성은 displayedOnComments이며, 이 속성은 배지가 사용자의 댓글에 표시되는지 여부를 제어합니다.

Example Request:

PUT 요청 예제

Copy

Run

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

Example Response:

응답

Copy

{
  "status": "success"
}

Possible Error Responses:

오류: 테넌트 ID 누락

Copy

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

오류: ID 누락

Copy

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

오류: 찾을 수 없음

Copy

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

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

이 엔드포인트를 통해 사용자 배지 할당을 삭제할 수 있습니다.

요청 예시:

DELETE 요청 예제

Copy

Run

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

응답 예시:

응답

Copy

{
  "status": "success"
}

가능한 오류 응답:

오류: 테넌트 ID 누락

Copy

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

오류: ID 누락

Copy

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

오류: 찾을 수 없음

Copy

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

---

사용자 배지 진행률 구조

UserBadgeProgress는 FastComments 시스템에서 사용자가 다양한 배지를 획득하기 위한 진행 상황을 나타내는 객체입니다.

이 추적은 사용자의 활동 및 커뮤니티 참여를 기반으로 언제 자동으로 배지를 수여할지 결정하는 데 도움이 됩니다.

The structure for the UserBadgeProgress object is as follows:

UserBadgeProgress 구조

Copy

export interface UserBadgeProgress {
    /** 이 진행 기록의 고유 식별자 */
    id: string
    /** 이 진행 기록이 속한 테넌트의 ID */
    tenantId: string
    /** 이 진행 기록이 추적하는 사용자의 ID */
    userId: string
    /** 시스템에서 사용자의 첫 댓글 ID */
    firstCommentId?: string
    /** 사용자의 첫 댓글 날짜(에포크 이후 밀리초) */
    firstCommentDate?: number
    /** 사용자 활동을 기반으로 자동 계산된 신뢰도 */
    autoTrustFactor?: number
    /** 관리자가 수동으로 설정한 신뢰도 */
    manualTrustFactor?: number
    /** 여러 지표를 포함한 상세 진행 객체, 키는 BadgeType 열거형과 일치함 */
    progress: {
        /** 0: CommentCount - 사용자가 작성한 댓글 수 */
        '0'?: number
        /** 1: CommentUpVotes - 사용자가 받은 추천(업보트) 수 */
        '1'?: number
        /** 2: CommentReplies - 사용자가 작성한 답글 수 */
        '2'?: number
        /** 3: CommentsPinned - 사용자가 고정한 댓글 수 */
        '3'?: number
        /** 4: Veteran - 사용자 계정 생성 후 경과 시간 */
        '4'?: number
        /** 5: NightOwl - 사용자가 야간 시간대에 게시한 횟수 */
        '5'?: number
        /** 6: FastReplyTime - 평균 답글 시간(밀리초) */
        '6'?: number
        /** 7: ModeratorCommentsDeleted - 모더레이터 배지의 경우 삭제된 댓글 수 */
        '7'?: number
        /** 8: ModeratorCommentsApproved - 모더레이터 배지의 경우 승인된 댓글 수 */
        '8'?: number
        /** 9: ModeratorCommentsUnapproved - 모더레이터 배지의 경우 미승인된 댓글 수 */
        '9'?: number
        /** 10: ModeratorCommentsReviewed - 모더레이터 배지의 경우 검토된 댓글 수 */
        '10'?: number
        /** 11: ModeratorCommentsMarkedSpam - 모더레이터 배지의 경우 스팸으로 표시된 댓글 수 */
        '11'?: number
        /** 12: ModeratorCommentsMarkedNotSpam - 모더레이터 배지의 경우 스팸 아님으로 표시된 댓글 수 */
        '12'?: number
        /** 13: RepliedToSpecificPage - 각 페이지에 대한 답글 수 */
        '13'?: Record<string, number>
    }
}

GET /api/v1/user-badge-progress

이 엔드포인트는 다양한 기준에 따라 사용자 배지 진행 기록을 가져올 수 있습니다.

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:

오류: 누락된 Tenant ID

Copy

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

오류: 잘못된 limit

Copy

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

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

이 엔드포인트를 사용하면 고유 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
    }
  }
}

가능한 오류 응답:

오류: 테넌트 ID 누락

Copy

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

오류: 찾을 수 없음

Copy

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

---

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

이 엔드포인트를 사용하면 사용자 ID로 사용자의 배지 진행 기록을 가져올 수 있습니다.

요청 예제:

GET 요청 예제

Copy

Run

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

응답 예제:

응답

Copy

{
  "status": "success",
  "userBadgeProgress": {
    "id": "progress123",
    "tenantId": "tenant001",
    "userId": "user456",
    "firstCommentId": "comment789",
    "firstCommentDate": 1650532511000,
    "autoTrustFactor": 0.75,
    "progress": {
      "0": 42,
      "1": 120,
      "2": 15,
      "3": 3,
      "5": 5,
      "6": 1800000,
      "8": 0,
      "7": 0
    }
  }
}

가능한 오류 응답:

오류: 테넌트 ID 누락

Copy

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

오류: 사용자 ID 누락

Copy

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

오류: 찾을 수 없음

Copy

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

---

결론

저희 API 문서가 포괄적이고 이해하기 쉬웠기를 바랍니다. 누락된 부분이 있다면 아래에 알려주세요.

언어 🇰🇷 한국어

API 리소스

집계

감사 로그

댓글

이메일 템플릿

해시태그

모더레이터

알림 수

알림

페이지

보류 중인 웹후크 이벤트

SSO 사용자

구독

테넌트 일별 사용량

테넌트

테넌트 패키지

테넌트 사용자

사용자

투표

도메인 구성

질문 구성

질문 결과

질문 결과 집계

사용자 배지

사용자 배지 진행률

FastComments API

생성된 SDKs

인증

보안 참고

인증 옵션 1 - 헤더

인증 옵션 2 - 쿼리 매개변수

API 리소스

리소스 사용량

참고!

데이터 집계

예제

예제: 고유 값 세기

예제: 고유 값 개수 세기

예제: 여러 필드 값 합계

예제: 여러 필드 값 평균

예제: 여러 필드의 최소/최대 값

예제: 여러 필드의 고유 값 세기

예제: 쿼리 생성 예제

예제: 검토 대기 댓글 수 세기

예제: 승인, 검토 및 스팸 댓글 분류

구조

감사 로그 구조

GET /api/v1/audit-logs

댓글 구조

댓글 텍스트 구조

태깅

해시태그

GET /api/v1/comments

페이지네이션

스레드

트리 설명

사용자 컨텍스트에서 댓글 가져오기

댓글을 트리로 가져오기

해시태그로 검색하여 트리형 댓글 가져오기

모든 요청 파라미터

응답

유용한 팁

URL ID

익명 액션

댓글이 반환되지 않는 경우

GET /api/v1/comments/:id

POST /api/v1/comments

PATCH /api/v1/comments/:id

DELETE /api/v1/comments/:id

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

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

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

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

이메일 템플릿 구조

참고

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

GET /api/v1/email-templates

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

POST /api/v1/email-templates