API | FastComments Docs

La API de FastComments

FastComments proporciona una API para interactuar con muchos recursos. Crea integraciones con nuestra plataforma, ¡o incluso desarrolla tus propios clientes!

En esta documentación encontrarás todos los recursos compatibles por la API documentados con sus tipos de solicitud y respuesta.

Para clientes Enterprise, todo el acceso a la API queda registrado en el Registro de Auditoría.

SDKs Generados

FastComments ahora genera una Especificación de la API a partir de nuestro código (esto aún no está completo, pero incluye muchas APIs).

También ahora tenemos SDKs para lenguajes populares:

Autenticación

La API se autentica pasando tu clave API ya sea como un encabezado X-API-KEY o como un parámetro de consulta API_KEY. También necesitarás tu tenantId para realizar llamadas a la API. Esto puede obtenerse desde la misma página que tu clave API.

Nota de seguridad

Estas rutas están pensadas para ser llamadas desde un servidor. NO las llames desde un navegador. Hacerlo expondrá tu clave API - esto proporcionará acceso total a tu cuenta a cualquiera que pueda ver el código fuente de una página!

Opción de autenticación uno - Encabezados

Encabezado: X-API-KEY
Encabezado: X-TENANT-ID

Opción de autenticación dos - Parámetros de consulta

Parámetro de consulta: API_KEY
Parámetro de consulta: tenantId

Recursos de la API

Uso de Recursos

Debe tenerse en cuenta que obtener datos de la API se cuenta como uso en su cuenta.

Cada recurso listará cuál es ese uso en su propia sección.

Algunos recursos cuestan más de servir que otros. Cada endpoint tiene un costo fijo de créditos por llamada de API. Para algunos endpoints, el número de créditos varía según las opciones y tamaños de respuesta.

El uso de la API se puede verificar en la página de Análisis de Facturación y se actualiza cada pocos minutos.

¡Nota!

Sugerimos leer primero la documentación de Páginas, para ayudar a limitar la confusión al determinar qué valores pasar para urlId en la API de Comentarios.

Agregue sus datos

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

Esta API Agrega documentos agrupándolos (si se proporciona groupBy) y aplicando múltiples operaciones. Se soportan diferentes operaciones (por ejemplo, sum, countDistinct, avg, etc.).

El costo es variable. Cada 500 objetos escaneados cuesta 1 crédito de API.

El uso máximo de memoria permitido por llamada de API por defecto es de 64MB, y por defecto solo puede tener una agregación ejecutándose a la vez. Si envía múltiples agregaciones simultáneamente, se pondrán en cola y se ejecutarán en el orden enviado. Las agregaciones pendientes esperarán un máximo de 60 segundos, después de eso la solicitud expirará. Las agregaciones individuales pueden ejecutarse hasta por 5 minutos.

Si tiene inquilinos administrados, puede agregar todos los recursos de inquilinos secundarios en una llamada pasando el parámetro de consulta parentTenantId.

Ejemplos

Ejemplo: Contar Únicos

Ejemplo cURL de Contar Valores Únicos

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

Respuesta de Contar Valores Únicos

Copy

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

Ejemplo: Contar Distintos

Ejemplo cURL de Contar Valores Distintos

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

Respuesta:

Respuesta de Contar Valores Distintos

Copy

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

Ejemplo: Sumar Valores de Múltiples Campos

Ejemplo cURL de Sumar Valores

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

Respuesta:

Respuesta de Sumar Valores

Copy

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

Ejemplo: Promediar Valores de Múltiples Campos

Ejemplo cURL de Promediar Valores

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

Respuesta:

Respuesta de Promediar Valores

Copy

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

Ejemplo: Valores Mín/Máx de Múltiples Campos

Ejemplo cURL de Valores Mín/Máx

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

Respuesta:

Respuesta de Valores Mín/Máx

Copy

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

Ejemplo: Contar Valores Únicos de Múltiples Campos

Ejemplo cURL de Contar Valores Únicos

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

Respuesta:

Respuesta de Contar Valores Únicos

Copy

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

Ejemplo: Creación de Consulta

Ejemplo cURL de Creación de Consulta

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

Respuesta:

Respuesta de Creación de Consulta

Copy

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

Ejemplo: Contar Comentarios Pendientes de Revisión

Ejemplo cURL de Contar Comentarios Pendientes de Revisión

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

Respuesta:

Respuesta de Contar Comentarios Pendientes de Revisión

Copy

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

Ejemplo: Desglose de Comentarios Aprobados, Revisados y Spam

Ejemplo cURL de Desglose de Comentarios

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

Respuesta:

Respuesta de Desglose de Comentarios

Copy

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

Estructuras

Estructura de Solicitud de Agregación

Copy

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

Estructura de Respuesta de Agregación

Copy

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

Los siguientes recursos pueden ser agregados:

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

Estructura de registro de auditoría

Un AuditLog es un objeto que representa un evento auditado para inquilinos que tienen acceso a esta función.

La estructura para el objeto AuditLog es la siguiente:

Estructura de 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;
}

El registro de auditoría es inmutable. Tampoco se puede escribir manualmente. FastComments.com es el único que puede decidir cuándo escribir en el registro de auditoría. Sin embargo, puede leer de él a través de esta API.

Los eventos en el registro de auditoría expiran después de dos años.

GET /api/v1/audit-logs

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

Esta API usa paginación, proporcionada por los parámetros skip, before y after. Los AuditLogs se devuelven en páginas de 1000, ordenados por when e id.

Obtener cada 1000 registros tiene un costo de crédito de 10.

Por defecto, recibirá una lista con los elementos más nuevos primero. De esta manera, puede consultar comenzando con skip=0, paginando hasta encontrar el último registro que ha consumido.

Alternativamente, puede ordenar del más antiguo al más nuevo, y paginar hasta que no haya más registros.

La ordenación se puede hacer configurando order a ASC o DESC. El valor predeterminado es ASC.

La consulta por fecha es posible a través de before y after como marcas de tiempo con milisegundos. before y after NO son inclusivos.

Ejemplo cURL de AuditLog

Copy

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

Estructura de Solicitud de AuditLog

Copy

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

Estructura de Respuesta de AuditLog

Copy

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

Estructura de comentario

Un objeto Comment representa un comentario dejado por un usuario.

La relación entre comentarios padre e hijo se define a través de parentId.

La estructura para el objeto Comment es la siguiente:

Estructura de Comment

Copy

interface Comment {
    /** READONLY: Set to true if the spam engine determined the comment was spam. **/
    aiDeterminedSpam?: boolean
    /** Whether the comment is approved to show. Set to true when saving the comment, else it will be hidden. **/
    approved?: boolean
    /** The user's avatar. **/
    avatarSrc?: string
    /** Child comments. Not populated in all scenarios. Used when asTree is set to true via the API. **/
    children: Comment[]
    /** The commenter's raw comment. **/
    comment: string
    /** READONLY: The commenter's comment parsed into HTML. **/
    commentHTML?: string
    /** The commenter's email. Required if anonymous commenting is off. **/
    commenterEmail?: string
    /** The commenter's link (for example, their blog). **/
    commenterLink?: string
    /** The commenter's name. Always required. If not available, set to something like "Anonymous". **/
    commenterName: string
    /** The date the comment was left, in UTC epoch. **/
    date: number
    /** The "display label" for the comment - for example "Admin", "Moderator", or something like "VIP User". **/
    displayLabel?: string
    /** The domain the comment was posted on. **/
    domain?: string
    /** READONLY: The number of times the comment was flagged. **/
    flagCount?: number
    /** The #hashtags written in the comment that were successfully parsed. You can also manually add hashtags, for querying, but they won't display in the comment text automatically. **/
    hashTags?: CommentHashTag[]
    /** READONLY: Does the comment contain images? **/
    hasImages?: boolean
    /** READONLY: Does the comment contain links? **/
    hasLinks?: boolean
    /** READONLY: The unique comment id. **/
    id: string
    /** Only on create! This is hashed for storage. **/
    ip?: string
    /** READONLY: Did the current user block the user that wrote this comment? **/
    isBlocked?: boolean
    /** READONLY: Is the comment by an admin? Automatically set based on userId. **/
    isByAdmin?: boolean
    /** READONLY: Is the comment by a moderator? Automatically set based on userId. **/
    isByModerator?: boolean
    /** Set to true if the comment was soft deleted (placeholder had to be left due to some other configuration). **/
    isDeleted?: boolean
    /** Set to true if the user's account was deleted and the comment had to be retained. **/
    isDeletedUser?: boolean
    /** READONLY: Is the flagged by the currently logged-in user (contextUserId)? **/
    isFlagged?: boolean
    /** Is the comment pinned? **/
    isPinned?: boolean
    /** Is the comment locked for new replies (moderators still can reply)? **/
    isLocked?: boolean
    /** Is the comment spam? **/
    isSpam?: boolean
    /** READONLY: Is the comment voted down for the current user (contextUserId)? **/
    isVotedDown?: boolean
    /** READONLY: Is the comment voted up for the current user (contextUserId)? **/
    isVotedUp?: boolean
    /** The locale the comment is in. If not provided, will be derived from the language accept HTTP header. **/
    locale?: 'de_de' | 'en_us' | 'es_es' | 'fr_fr' | 'it_it' | 'ja_jp' | 'ko_kr' | 'pl_pl' | 'pt_br' | 'ru_ru' | 'tr_tr' | 'zh_cn' | 'zh_tw'
    /** READONLY: The @mentions written in the comment that were successfully parsed. **/
    mentions?: CommentUserMention[]
    /** Optional metadata associated with the comment. **/
    meta?: Record<string, string | number | boolean>
    /** The optional list of moderation group ids associated with this comment. **/
    moderationGroupIds?: string[]|null
    /** READONLY: The id of the vote object that corresponds to the vote from the current user (contextUserId) on this comment. **/
    myVoteId?: string
    /** Whether notifications were sent for this comment for commenters. To prevent notifications being sent on imports, set this to true. **/
    notificationSentForParent?: boolean
    /** Whether notifications were sent for this comment for tenant users. To prevent notifications being sent on imports, set this to true. **/
    notificationSentForParentTenant?: boolean
    /** The title of the page this comment was on. **/
    pageTitle?: string
    /** If we're replying to a comment, this is the ID that we are replying to. **/
    parentId?: string|null
    /** Whether the comment is marked reviewed. **/
    reviewed: boolean
    /** The tenant id where the comment belongs. **/
    tenantId: string
    /** The user that wrote the comment. Created automatically when saving a comment with a name/email. **/
    userId?: string|null
    /** The URL to the location that this comment is visible, like a blog post. **/
    url: string
    /** A "cleaned" version of the urlId you passed us. When saving, you specify this field, but when you fetch the comment back this will be "cleaned" and your original value moved to "urlIdRaw". **/
    urlId: string
    /** READONLY: The original urlId you passed us. **/
    urlIdRaw?: string
    /** Is the user and this comment verified? **/
    verified: boolean
    /** Number of votes up. **/
    votesUp?: number
    /** Number of votes down. **/
    votesDown?: number
    /** The "karma" of the comment (= votes up - votes down). **/
    votes?: number
}

Algunos de estos campos están marcados como READONLY - estos son devueltos por la API pero no pueden ser establecidos.

Estructura del Texto del Comentario

Los comentarios se escriben en un sabor de markdown de FastComments, que es simplemente markdown más etiquetas tradicionales estilo bbcode para imágenes, como [img]ruta[/img].

El texto se almacena en dos campos. El texto que el usuario ingresó se almacena sin modificar en el campo comment. Esto se renderiza y almacena en el campo commentHTML.

Las etiquetas HTML permitidas son b, u, i, strike, pre, span, code, img, a, strong, ul, ol, li, y br.

Se recomienda renderizar el HTML, ya que es un subconjunto muy pequeño de HTML, construir un renderizador es bastante sencillo. Hay múltiples bibliotecas para React Native y Flutter, por ejemplo, para ayudar con esto.

Puede elegir renderizar el valor no normalizado del campo comment. Un ejemplo de analizador está aquí..

El ejemplo de analizador también podría ajustarse para trabajar con HTML, y transformar las etiquetas HTML en elementos esperados para renderizar para su plataforma.

Etiquetado

Cuando los usuarios son etiquetados en un comentario, la información se almacena en una lista llamada mentions. Cada objeto en esa lista tiene la siguiente estructura.

El Objeto de Menciones de Comentario

Copy

Run

interface CommentUserMention {
    /** The user id. For SSO users, this will have your tenant id prefixed. **/
    id: string
    /** The final @mention tag text, including the @ symbol. **/
    tag: string
    /** The original @mention tag text, including the @ symbol. **/
    rawTag: string
    /** What type of user was tagged. user = FastComments.com account. sso = SSOUser. **/
    type: 'user'|'sso'
    /** If the user opts out of notifications, this will still be set to true. **/
    sent: boolean
}

HashTags

Cuando se usan hashtags y se analizan con éxito, la información se almacena en una lista llamada hashTags. Cada objeto en esa lista tiene la siguiente estructura. Los hashtags también pueden agregarse manualmente al array hashTags del comentario para consultas, si se establece retain.

El Objeto HashTag de Comentario

Copy

Run

interface CommentHashTag {
    /** The hashtag id. **/
    id: string
    /** The final #hashtag tag text, including the # symbol. **/
    tag: string
    /** If the hashtag is associated with a custom URL, this will be defined. **/
    url?: string
    /** If we should retain the hashtag, even if it does not exist in the comment text, when the comment is updated. Useful for tagging comments without changing comment text. **/
    retain?: boolean
}

GET /api/v1/comments

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

Esta API se usa para obtener comentarios para mostrar a un usuario. Por ejemplo, filtra automáticamente los comentarios no aprobados o spam.

Paginación

La paginación se puede hacer de dos maneras, dependiendo de los requisitos de rendimiento y caso de uso:

Más rápido: Paginación Precalculada:
1. Así es como funciona FastComments cuando usa nuestros widgets y clientes preconstruidos.
2. Hacer clic en "siguiente" simplemente aumenta el conteo de páginas.
3. Puede pensar en esto como ser recuperado por un almacén de clave-valor.
4. De esta manera, simplemente defina un parámetro page comenzando en 0 y una dirección de ordenamiento como direction.
5. Los tamaños de página se pueden personalizar a través de reglas de personalización.
Más flexible: Paginación Flexible:
1. De esta manera puede definir parámetros personalizados limit y skip. No pase page.
2. También se soporta la direction de ordenamiento.
3. limit es el total a devolver después de que se aplica skip.
  - Ejemplo: establezca skip = 200, limit = 100 cuando tamaño de página = 100 y page = 2.
4. Los comentarios hijos aún cuentan en la paginación. Puede evitar esto usando la opción asTree.
  - Puede paginar hijos a través de limitChildren y skipChildren.
  - Puede limitar la profundidad de los hilos devueltos a través de maxTreeDepth.

Hilos

Cuando usa Paginación Precalculada, los comentarios se agrupan por página y los comentarios en hilos afectan la página general.
1. De esta manera, los hilos se pueden determinar en el cliente basándose en parentId.
2. Por ejemplo, con una página con un comentario de nivel superior, y 29 respuestas, y configurando page=0 en la API - obtendrá solo el comentario de nivel superior y los 29 hijos.
3. Imagen de ejemplo aquí ilustrando múltiples páginas.
Cuando usa Paginación Flexible, puede definir un parámetro parentId.
1. Establezca esto a null para obtener solo comentarios de nivel superior.
2. Luego para ver hilos, llame a la API nuevamente y pase parentId.
3. Una solución común es hacer una llamada a la API para los comentarios de nivel superior y luego hacer llamadas paralelas a la API para obtener comentarios para los hijos de cada comentario.
¡NUEVO Desde Feb 2023! Obtener como árbol usando &asTree=true.
1. Puede pensar en esto como Paginación Flexible como Árbol.
2. Solo los comentarios de nivel superior cuentan en la paginación.
3. Establezca parentId=null para iniciar el árbol en la raíz (debe establecer parentId).
4. Establezca skip y limit para paginación.
5. Establezca asTree a true.
6. El costo de créditos aumenta por 2x, ya que nuestro backend tiene que hacer mucho más trabajo en este escenario.
7. Establezca maxTreeDepth, limitChildren y skipChildren según lo deseado.

Árboles Explicados

Cuando usa asTree, puede ser difícil razonar sobre la paginación. Aquí hay un gráfico útil:

Diagrama de Paginación de Árbol

Obtener Comentarios en el Contexto de un Usuario

La API /comments se puede usar en dos contextos, para diferentes casos de uso:

Para devolver comentarios ordenados y etiquetados con información para construir su propio cliente.
- En este caso, defina un parámetro de consulta contextUserId.
Para obtener comentarios desde su backend para integraciones personalizadas.
- La plataforma usará esto por defecto sin contextUserId.

Paginación Precalculada de Comentarios

Copy

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

Paginación Flexible de Comentarios

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'

Paginación Flexible de Comentarios en Contexto de Usuario

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'

Paginación Flexible de Comentarios en Contexto de Usuario Solo para Comentarios de Nivel Superior

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'

Obtener Comentarios como Árbol

Es posible obtener los comentarios devueltos como un árbol, con la paginación contando solo los comentarios de nivel superior.

Comentarios Como Árbol en Contexto de Usuario

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'

¿Quiere obtener solo los comentarios de nivel superior y los hijos inmediatos? Aquí hay una forma:

Comentarios Como Árbol con Profundidad Máxima

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'

Sin embargo, en su UI podría necesitar saber si mostrar un botón de "mostrar respuestas" en cada comentario. Cuando obtiene comentarios a través de un árbol hay una propiedad hasChildren etiquetada en los comentarios cuando aplica.

Obtener Comentarios como Árbol, Buscando por Hash Tag

Es posible buscar por hashtag usando la API, a través de todo su inquilino (no limitado a una página, o urlId).

En este ejemplo, omitimos urlId, y buscamos por múltiples hashtags. La API solo devolverá comentarios que tengan todos los hashtags solicitados.

Comentarios Como Árbol en Contexto de Usuario, Por Hash Tag

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'

Todos los Parámetros de Solicitud

Estructura de Solicitud de Comentarios

Copy

interface CommentsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The urlId (page url, or article id) the comments are associated with. **/
    urlId?: string
    /** Limit the comments returned by this user. **/
    userId?: string
    /** Use this to search by hashtag. To drill down to the intersection of multiple hashtags, do &hashTag=a&hashTag=b. **/
    hashTag?: string
    /** The sort direction. Default is MR (Most Relevant). Other options are OF (Oldest First) and NF (Newest First). **/
    direction?: 'MR' | 'OF' | 'NF'
    /** Precalculated Pagination: The page to fetch, starting with 0. Pass -1 for all comments (up to 250). **/
    page?: number
    /** Flexible Pagination: How many comments should we return? **/
    limit?: number
    /** Flexible Pagination: How many child comments should we return for each parent? **/
    limitChildren?: number
    /** Flexible Pagination: How many comments should we skip? **/
    skip?: number
    /** Flexible Pagination: How many child comments should we skip for each parent? **/
    skipChildren?: number
    /** For determining blocked and flagged comments. **/
    contextUserId?: string
    /** For determining blocked and flagged comments. **/
    anonUserId?: string
    /** For fetching child comments. **/
    parentId?: string
    /** For fetching as a tree. **/
    asTree?: boolean
    /** How far into the tree should we return data? 0 returns no children. 1 returns immediate children, etc. **/
    maxTreeDepth?: number
}

La Respuesta

Estructura de Respuesta de Comentarios

Copy

interface CommentsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'missing-date' | 'unauthorized-page' | 'invalid-pagination-request' | 'invalid-limit' | 'invalid-limit-children' | 'invalid-skip' | 'invalid-skip-children' | 'invalid-max-tree-depth'
    /** Included on failure. **/
    reason?: string
    /** The comments! **/
    comments: Comment[]
}

Consejos Útiles

URL ID

Probablemente quiera usar la API Comment con el parámetro urlId. Puede llamar a la API Pages primero, para ver cómo lucen los valores urlId disponibles para usted.

Acciones Anónimas

Para comentarios anónimos probablemente quiera pasar anonUserId cuando obtiene comentarios, y cuando realiza marcado y bloqueo.

(!) Esto es requerido para muchas tiendas de aplicaciones ya que los usuarios deben poder marcar contenido creado por usuarios que pueden ver, incluso si no han iniciado sesión. No hacerlo puede causar que su aplicación sea eliminada de dicha tienda.

Comentarios No Devueltos

Verifique que sus comentarios estén aprobados, y no sean spam.

GET /api/v1/comments/:id

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

Esta API proporciona la capacidad de obtener un único comentario por id.

Ejemplo cURL de Obtener Comentario por ID

Copy

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

Estructura de Solicitud de Obtener Comentario por ID

Copy

interface CommentsGetByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Obtener Comentario por ID

Copy

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

POST /api/v1/comments

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

Este endpoint de API proporciona la capacidad de crear comentarios.

Los casos de uso comunes son interfaces personalizadas, integraciones o importaciones.

Notas:

Esta API puede actualizar el widget de comentarios "en vivo" si se desea (esto aumenta creditsCost de 1 a 2).
Esta API creará automáticamente objetos de usuario en nuestro sistema si se proporciona email.
Intentar guardar dos comentarios con diferentes emails, pero el mismo nombre de usuario, resultará en un error para el segundo comentario.
Si está especificando parentId, y un comentario hijo tiene notificationSentForParent como false, enviaremos notificaciones para el comentario padre. Esto se hace cada hora (agrupamos las notificaciones para disminuir el número de emails enviados).
Si desea enviar emails de bienvenida al crear usuarios, o emails de verificación de comentarios, establezca sendEmails a true en los parámetros de consulta.
Los comentarios creados a través de esta API aparecerán en las páginas de Análisis y Moderación de la aplicación de administración.
Las "malas palabras" aún se enmascaran en los nombres de los comentaristas y el texto del comentario si la configuración está activada.
Los comentarios creados a través de esta API aún pueden ser verificados para spam si se desea.
La configuración como longitud máxima del comentario, si se configura a través de la página de administración de Reglas de Personalización, se aplicará aquí.

Los datos mínimos requeridos para enviar que se mostrarán en el widget de comentarios, son los siguientes:

Ejemplo cURL Mínimo de POST de Comentario

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

Una solicitud más realista podría verse así:

Ejemplo cURL de POST de Comentario

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

Estructura de Solicitud de POST de Comentario

Copy

interface CommentPostQueryParams {
    tenantId: string
    API_KEY: string
    doSpamCheck?: 'true' | 'false'
    /** Whether the comment should appear "live" to users viewing instances of the comment widget with the same urlId. NOTE: Doubles credit cost from 1 to 2. **/
    isLive?: 'true' | 'false'
    sendEmails?: 'true' | 'false'
    populateNotifications?: 'true' | 'false'
}

Estructura de Respuesta de POST de Comentario

Copy

interface CommentPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-comment' | 'comment-too-big' | 'hash-tags-readonly' | 'mentions-readonly' | 'invalid-user' | 'unauthorized' | 'invalid-date' | 'invalid-name' | 'invalid-name-is-email' | 'banned' | 'invalid-email';
    /** Included on failure. **/
    reason?: string
    /** The created comment. **/
    comment?: Comment
    /** The associated user, which may or may not have already existed. **/
    user?: User
}

PATCH /api/v1/comments/:id

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

Este endpoint de API proporciona la capacidad de actualizar un único comentario.

Notas:

Esta API puede actualizar el widget de comentarios "en vivo" si se desea (esto aumenta el creditsCost base de 1 a 2).
- Esto puede hacer que la migración de comentarios entre páginas sea "en vivo" (cambiando urlId).
- Las migraciones cuestan 2 créditos adicionales ya que las páginas son precalculadas y esto es intensivo en CPU.
A diferencia de la API de creación, esta API NO creará automáticamente objetos de usuario en nuestro sistema si se proporciona email.
Los comentarios actualizados a través de esta API aún pueden ser verificados para spam si se desea.
La configuración como longitud máxima del comentario, si se configura a través de la página de administración de Reglas de Personalización, se aplicará aquí.
Para permitir a los usuarios actualizar el texto de su comentario, puede simplemente especificar comment en el cuerpo de la solicitud. Generaremos el commentHTML resultante.
- Si define tanto comment como commentHTML no generaremos automáticamente el HTML.
- Si el usuario agrega menciones o hashtags en su nuevo texto, se procesará como la API POST.
Cuando actualice commenterEmail en un comentario, es mejor también especificar userId. De lo contrario, debe asegurarse de que el usuario con este email pertenezca a su inquilino, o la solicitud fallará.

Ejemplo cURL Mínimo de PATCH de Comentario

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

Estructura de Solicitud de PATCH de Comentario

Copy

interface CommentPatchQueryParams {
    tenantId: string
    API_KEY: string
    /** The user doing the update. If desired can be used to check that they can edit the comment.  **/
    contextUserId?: string
    /** Should we check if the new comment looks like spam?  **/
    doSpamCheck?: 'true' | 'false'
    /** Whether the comment should appear "live" to users viewing instances of the comment widget with the same urlId. NOTE: Doubles credit cost from 1 to 2. **/
    isLive?: 'true' | 'false'
}

Estructura de Respuesta de PATCH de Comentario

Copy

interface CommentPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-comment' | 'comment-too-big' | 'hash-tags-readonly' | 'mentions-readonly' | 'invalid-user' | 'unauthorized' | 'invalid-date' | 'invalid-name' | 'invalid-name-is-email' | 'banned' | 'invalid-email' | 'invalid-input' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
}

DELETE /api/v1/comments/:id

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

Este endpoint de API proporciona la capacidad de eliminar un comentario.

Notas:

Esta API puede actualizar el widget de comentarios "en vivo" si se desea (esto aumenta creditsCost de 1 a 2).
Esta API eliminará todos los comentarios secundarios.

Ejemplo cURL de DELETE de Comentario

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'

Estructura de Solicitud de DELETE de Comentario

Copy

interface CommentDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** The user doing the update. If desired can be used to check that they can delete the comment.  **/
    contextUserId?: string
    /** Whether the comment should be deleted "live" to users viewing instances of the comment widget with the same urlId. NOTE: Doubles credit cost from 1 to 2. **/
    isLive?: 'true' | 'false'
}

Estructura de Respuesta de DELETE de Comentario

Copy

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

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

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

Este endpoint de API proporciona la capacidad de marcar un comentario para un usuario específico.

Notas:

Esta llamada siempre debe hacerse en el contexto de un usuario. El usuario puede ser un Usuario de FastComments.com, Usuario SSO o Usuario de Inquilino.
Si se establece un umbral de marcar para ocultar, el comentario se ocultará automáticamente en vivo después de haber sido marcado el número definido de veces.
Después de ser automáticamente desaprobado (oculto) - el comentario solo puede ser re-aprobado por un administrador o moderador. Desmarcar no re-aprobará el comentario.

Ejemplo cURL de Marcar Comentario

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'

Para marcar anónimamente, debemos especificar un anonUserId. Este puede ser un ID que representa la sesión anónima, o un UUID aleatorio. Esto nos permite soportar marcar y desmarcar comentarios incluso si un usuario no ha iniciado sesión. De esta manera, el comentario puede ser marcado como marcado cuando los comentarios se obtienen con el mismo anonUserId.

Ejemplo cURL de Marcar Comentario Anónimo

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'

Estructura de Solicitud de Marcar Comentario

Copy

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

Estructura de Respuesta de Marcar Comentario

Copy

interface CommentFlagResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id'
    /** Included on failure. **/
    reason?: string
    /** Was the comment un-approved (hidden) due to being flagged too many times? **/
    wasUnapproved?: boolean;
}

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

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

Este endpoint de API proporciona la capacidad de desmarcar un comentario para un usuario específico.

Notas:

Esta llamada siempre debe hacerse en el contexto de un usuario. El usuario puede ser un Usuario de FastComments.com, Usuario SSO o Usuario de Inquilino.
Después de que un comentario es automáticamente desaprobado (oculto) - el comentario solo puede ser re-aprobado por un administrador o moderador. Desmarcar no re-aprobará el comentario.

Ejemplo cURL de Desmarcar Comentario

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'

Para desmarcar anónimamente, debemos especificar un anonUserId. Este puede ser un ID que representa la sesión anónima, o un UUID aleatorio.

Ejemplo cURL de Desmarcar Comentario Anónimo

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'

Estructura de Solicitud de Desmarcar Comentario

Copy

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

Estructura de Respuesta de Desmarcar Comentario

Copy

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

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

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

Este endpoint de API proporciona la capacidad de bloquear a un usuario que escribió un comentario dado. Soporta el bloqueo de comentarios escritos por Usuarios de FastComments.com, Usuarios SSO y Usuarios de Inquilino.

Soporta un parámetro de cuerpo commentIdsToCheck para verificar si algún otro comentario potencialmente visible en el cliente debe ser bloqueado/desbloqueado después de realizar esta acción.

Notas:

Esta llamada siempre debe hacerse en el contexto de un usuario. El usuario puede ser un Usuario de FastComments.com, Usuario SSO o Usuario de Inquilino.
El userId en la solicitud es el usuario que está haciendo el bloqueo. Por ejemplo: Usuario A quiere Bloquear a Usuario B. Pase userId=Usuario A y el id del comentario que escribió Usuario B.
Los comentarios completamente anónimos (sin id de usuario, sin email) no pueden ser bloqueados y se devolverá un error.

Ejemplo cURL de Bloqueo de Comentario

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'

Para bloqueo anónimo, debemos especificar un anonUserId. Este puede ser un ID que representa la sesión anónima, o un UUID aleatorio. Esto nos permite soportar el bloqueo de comentarios incluso si un usuario no ha iniciado sesión obteniendo los comentarios con el mismo anonUserId.

Ejemplo cURL de Bloqueo de Comentario Anónimo

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'

Estructura de Solicitud de Bloqueo de Comentario

Copy

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

Estructura de Respuesta de Bloqueo de Comentario

Copy

interface CommentBlockResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id' | 'comment-cannot-be-blocked'
    /** Included on failure. **/
    reason?: string
    /** If commentIdsToCheck is defined, entries in this map with true are also blocked. **/
    commentStatuses?: Record<string, boolean>;
}

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

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

Este endpoint de API proporciona la capacidad de desbloquear a un usuario que escribió un comentario dado. Soporta el desbloqueo de comentarios escritos por Usuarios de FastComments.com, Usuarios SSO y Usuarios de Inquilino.

Soporta un parámetro de cuerpo commentIdsToCheck para verificar si algún otro comentario potencialmente visible en el cliente debe ser bloqueado/desbloqueado después de realizar esta acción.

Notas:

Esta llamada siempre debe hacerse en el contexto de un usuario. El usuario puede ser un Usuario de FastComments.com, Usuario SSO o Usuario de Inquilino.
El userId en la solicitud es el usuario que está haciendo el desbloqueo. Por ejemplo: Usuario A quiere Desbloquear a Usuario B. Pase userId=Usuario A y el id del comentario que escribió Usuario B.
Los comentarios completamente anónimos (sin id de usuario, sin email) no pueden ser bloqueados y se devolverá un error.

Ejemplo cURL de Desbloqueo de Comentario

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'

Ejemplo cURL de Desbloqueo de Comentario Anónimo

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'

Estructura de Solicitud de Desbloqueo de Comentario

Copy

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

Estructura de Respuesta de Desbloqueo de Comentario

Copy

interface CommentUnBlockResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id' | 'comment-cannot-be-blocked'
    /** Included on failure. **/
    reason?: string
    /** If commentIdsToCheck is defined, entries in this map with true are still blocked. If false, you might want to un-hide the comments from the user so they don't have to refresh. **/
    commentStatuses?: Record<string, boolean>;
}

Estructura de plantilla de correo electrónico

Un objeto EmailTemplate representa la configuración para una plantilla de email personalizada, para un inquilino.

El sistema seleccionará la plantilla de email a usar mediante:

Su identificador de tipo, lo llamamos emailTemplateId. Estos son constantes.
El domain. Primero intentaremos encontrar una plantilla para el dominio al que está vinculado el objeto relacionado (como un Comment), y si no se encuentra una coincidencia entonces intentaremos encontrar una plantilla donde domain sea null o *.

La estructura del objeto EmailTemplate es la siguiente:

Estructura de Plantilla de Email

Copy

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

Notas

Puede obtener los valores válidos de emailTemplateId desde el endpoint /definitions.
El endpoint /definitions también incluye las traducciones predeterminadas y datos de prueba.
Las plantillas fallarán al guardar con estructura o datos de prueba inválidos.

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

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

Los EmailTemplates individuales pueden obtenerse por su id correspondiente (NO emailTemplateId).

Ejemplo cURL de EmailTemplate por ID

Copy

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

Estructura de Solicitud de EmailTemplate por ID

Copy

interface EmailTemplatesByIdRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de EmailTemplate por ID

Copy

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

GET /api/v1/email-templates

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

Esta API usa paginación, proporcionada por el parámetro de consulta page. Los EmailTemplates se devuelven en páginas de 100, ordenados por createdAt y luego id.

Ejemplo cURL de EmailTemplate

Copy

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

Estructura de Solicitud de EmailTemplate

Copy

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

Estructura de Respuesta de EmailTemplate

Copy

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

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

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

Este endpoint de API proporciona la capacidad de actualizar una plantilla de email especificando solo el id y los atributos a actualizar.

Tenga en cuenta que todas las mismas validaciones para crear una plantilla también aplican, por ejemplo:

La plantilla debe renderizarse. Esto se verifica con cada actualización.
No puede tener plantillas duplicadas para el mismo dominio (de lo contrario una sería ignorada silenciosamente).

Ejemplo cURL de PATCH de EmailTemplate

Copy

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

Estructura de Solicitud de PATCH de EmailTemplate

Copy

interface EmailTemplatePatchQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de PATCH de EmailTemplate

Copy

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

POST /api/v1/email-templates

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

Este endpoint de API proporciona la capacidad de crear plantillas de email.

Notas:

No puede tener múltiples plantillas con el mismo emailTemplateId con el mismo dominio.
Pero puede tener una plantilla comodín (domain = * y una plantilla específica de dominio para el mismo emailTemplateId).
Especificar domain solo es relevante si tiene diferentes dominios, o quiere usar plantillas específicas para pruebas (domain establecido a localhost etc).
Si especifica domain debe coincidir con un DomainConfig. En caso de error se proporciona una lista de dominios válidos.
La sintaxis de plantilla es EJS y se renderiza con un timeout de 500ms. P99 para renderizado es <5ms, así que si llega a 500ms algo está mal.
Su plantilla debe renderizarse con su testData dado para guardar. Los errores de renderizado se agregan y reportan en el dashboard (pronto disponible vía API).

Los datos mínimos requeridos para agregar una plantilla son los siguientes:

Ejemplo cURL Mínimo de POST de EmailTemplate

Copy

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

Puede querer tener plantillas por sitio, en cuyo caso define domain:

Ejemplo cURL de POST de EmailTemplate

Copy

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

Estructura de Solicitud de POST de EmailTemplate

Copy

interface EmailTemplatePostQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de POST de EmailTemplate

Copy

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

POST /api/v1/email-templates/render

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

Este endpoint de API proporciona la capacidad de previsualizar plantillas de email.

Ejemplo cURL Mínimo de POST de Vista Previa de EmailTemplate

Copy

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

Estructura de Solicitud de POST de EmailTemplate

Copy

interface EmailTemplatePostQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de POST de EmailTemplate

Copy

interface EmailTemplatePostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'unexpected-param' | 'does-not-render';
    /** Included on failure. **/
    reason?: string
    /** The rendered HTML on success. **/
    html?: string
}

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

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

Esta ruta proporciona la eliminación de un único EmailTemplate por id.

Ejemplo cURL de Eliminación de EmailTemplate

Copy

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

Estructura de Solicitud de Eliminación de EmailTemplate

Copy

interface EmailTemplateRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Eliminación de EmailTemplate

Copy

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

Estructura de hashtag

Un objeto HashTag representa una etiqueta que puede ser dejada por un usuario. Los HashTags pueden usarse para vincular a una pieza externa de contenido o para vincular comentarios relacionados juntos.

La estructura del objeto HashTag es la siguiente:

Estructura de HashTag

Copy

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

Notas:

En algunos endpoints de API verá que el hashtag se usa en la URL. Recuerde usar valores codificados en URI. Por ejemplo, # debe representarse como %23.
Algunos de estos campos están marcados como READONLY - estos son devueltos por la API pero no pueden ser establecidos.

GET /api/v1/hash-tags

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

Esta API usa paginación, proporcionada por el parámetro de consulta page. Los HashTags se devuelven en páginas de 100, ordenados por tag.

Ejemplo cURL de HashTag

Copy

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

Estructura de Solicitud de HashTag

Copy

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

Estructura de Respuesta de HashTag

Copy

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

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

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

Esta ruta proporciona la capacidad de actualizar un único HashTag.

Ejemplo cURL de Actualización de HashTag

Copy

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

Estructura de Solicitud de Actualización de HashTag

Copy

interface HashTagPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Actualización de HashTag

Copy

interface HashTagPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist' | 'url-too-long' | 'invalid-tag' |  'already-exists'
    /** Included on failure. **/
    reason?: string
    hashTag?: HashTag; // We return the complete updated hashtag on success.
}

POST /api/v1/hash-tags

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

Esta ruta proporciona la capacidad de agregar un único HashTag.

Ejemplo cURL de Creación de HashTag

Copy

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

Estructura de Solicitud de Creación de HashTag

Copy

interface HashTagPostQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Creación de HashTag

Copy

interface HashTagPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist' | 'url-too-long' | 'invalid-tag'
    /** Included on failure. **/
    reason?: string
    hashTag?: HashTag; // We return the complete created hashtag on success.
}

POST /api/v1/hash-tags/bulk

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

Esta ruta proporciona la capacidad de agregar hasta 100 objetos HashTag a la vez.

Ejemplo cURL de Creación Masiva de HashTag

Copy

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

Estructura de Solicitud de Creación Masiva de HashTag

Copy

interface HashTagPostQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Creación Masiva de HashTag

Copy

interface HashTagBulkPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist' | 'url-too-long' | 'invalid-tag'
    /** Included on failure. **/
    reason?: string
    results?: HashTagPostResponse[]; // We return a list of HashTagPostResponse objects for each provided tag.
}

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

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

Esta ruta proporciona la eliminación de un HashTag usuario por la etiqueta proporcionada.

Tenga en cuenta que a menos que la creación automática de HashTag esté deshabilitada, los hashtags pueden ser recreados por un usuario que proporcione el hashtag al comentar.

Ejemplo cURL de Eliminación de HashTag

Copy

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

Estructura de Solicitud de Eliminación de HashTag

Copy

interface HashTagDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Eliminación de HashTag

Copy

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

Estructura de moderador

Un objeto Moderator representa la configuración para un moderador.

Hay tres tipos de moderadores:

Usuarios administradores que tienen la bandera isCommentModeratorAdmin.
Usuarios SSO con la bandera isCommentModeratorAdmin.
Comentaristas regulares, o usuarios de FastComments.com, que son invitados como Moderadores.

La estructura Moderator se usa para representar el Estado de Moderación del caso de uso 3.

Si quiere invitar a un usuario a ser moderador, vía la API, use la API de Moderator creando un Moderator e invitándolo.

Si el usuario no tiene una cuenta de FastComments.com, el email de invitación les ayudará a configurarse. Si ya tienen una cuenta, se les dará acceso de moderación a su inquilino y el userId del objeto Moderator se actualizará para apuntar a su usuario. No tendrá acceso API a su usuario, ya que en este caso les pertenece a ellos mismos y es gestionado por FastComments.com.

Si requiere gestión completa de la cuenta del usuario, recomendamos usar SSO, o agregarlos como un Usuario de Inquilino y luego agregar un objeto Moderator para rastrear sus estadísticas.

La estructura Moderator puede usarse como un mecanismo de seguimiento de estadísticas para los casos de uso 1 y 2. Después de crear el usuario, agregue un objeto Moderator con su userId definido y sus estadísticas serán rastreadas en la Página de Moderadores de Comentarios.

La estructura del objeto Moderator es la siguiente:

Estructura de 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

Esta ruta devuelve un único moderador por su id.

Ejemplo cURL de Moderator por ID

Copy

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

Estructura de Solicitud de Moderator

Copy

interface ModeratorByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Moderator

Copy

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

GET /api/v1/moderators

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

Esta API usa paginación, proporcionada por el parámetro de consulta skip. Los Moderators se devuelven en páginas de 100, ordenados por createdAt e id.

El costo se basa en el número de moderadores devueltos, costando 1 crédito por cada 10 moderadores devueltos.

Ejemplo cURL de Moderator

Copy

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

Estructura de Solicitud de Moderator

Copy

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

Estructura de Respuesta de Moderator

Copy

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

PATCH /api/v1/moderators/:id

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

Este endpoint de API proporciona la capacidad de actualizar un Moderator por id.

Actualizar un Moderator tiene las siguientes restricciones:

Los siguientes valores no pueden proporcionarse al actualizar un Moderator:
- acceptedInvite
- markReviewedCount
- deletedCount
- markedSpamCount
- approvedCount
- editedCount
- bannedCount
- verificationId
- createdAt
Cuando se especifica un userId, ese usuario debe existir.
Cuando se especifica un userId, deben pertenecer al mismo tenantId especificado en los parámetros de consulta.
Dos moderadores en el mismo inquilino no pueden agregarse con el mismo email.
No puede cambiar el tenantId asociado con un Moderator.

Ejemplo cURL de PATCH de Moderator

Copy

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

Estructura de Solicitud de PATCH de Moderator

Copy

interface ModeratorPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de PATCH de Moderator

Copy

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

POST /api/v1/moderators

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

Esta ruta proporciona la capacidad de agregar un único Moderator.

Crear un Moderator tiene las siguientes restricciones:

Siempre debe proporcionarse un name y email. Un userId es opcional.
Los siguientes valores no pueden proporcionarse al crear un Moderator:
- acceptedInvite
- markReviewedCount
- deletedCount
- markedSpamCount
- approvedCount
- editedCount
- bannedCount
- verificationId
- createdAt
Cuando se especifica un userId, ese usuario debe existir.
Cuando se especifica un userId, deben pertenecer al mismo tenantId especificado en los parámetros de consulta.
Dos moderadores en el mismo inquilino no pueden agregarse con el mismo email.

Podemos crear un Moderator para un usuario del cual solo conocemos el email:

Ejemplo cURL de Creación de Moderator vía Email

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

O podemos crear un Moderator para un usuario que pertenece a nuestro inquilino, para rastrear sus estadísticas de moderación:

Ejemplo cURL de Creación de Moderator vía Usuario de Inquilino

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

Estructura de Solicitud de Creación de Moderator

Copy

interface ModeratorPostQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Creación de Moderator

Copy

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

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

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

Esta ruta proporciona la capacidad de invitar a un único Moderator.

Las siguientes restricciones existen para enviar un email de invitación a un Moderator:

El Moderator ya debe existir.
El fromName no puede tener más de 100 caracteres.

Notas:

Si un usuario con el email proporcionado ya existe, será invitado a moderar los comentarios de su inquilino.
Si un usuario con el email proporcionado no existe el enlace de invitación los guiará a través de la creación de su cuenta.
La invitación expirará después de 30 días.

Podemos crear un Moderator para un usuario del cual solo conocemos el email:

Ejemplo cURL de Invitación de Moderator

Copy

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

Esto enviará un email como Bob de TenantName te está invitando a ser moderador...

Estructura de Solicitud de Invitación de Moderator

Copy

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

Estructura de Respuesta de Invitación de Moderator

Copy

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

DELETE /api/v1/moderators/:id

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

Esta ruta proporciona la eliminación de un Moderator por id.

Ejemplo cURL de Eliminación de Moderator

Copy

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

Estructura de Solicitud de Eliminación de Moderator

Copy

interface ModeratorDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Eliminación de Moderator

Copy

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

Estructura de conteo de notificaciones

Un objeto NotificationCount representa el conteo de notificaciones no leídas y metadatos para un usuario.

Si no hay notificaciones no leídas, no habrá un NotificationCount para el usuario.

Los objetos NotificationCount se crean automáticamente y no pueden crearse vía la API. También expiran después de un año.

Puede limpiar el conteo de notificaciones no leídas de un usuario eliminando su NotificationCount.

La estructura del objeto NotificationCount es la siguiente:

Estructura de NotificationCount

Copy

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

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

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

Esta ruta devuelve un único NotificationCount por id de usuario. Con SSO, el id de usuario está en el formato <tenant id>:<user id>.

Si no hay notificaciones no leídas, no habrá un NotificationCount - así que obtendrá un 404.

Esto es diferente de notifications/count en que es mucho más rápido, pero no permite filtrado.

Ejemplo cURL de NotificationCount por ID

Copy

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

Estructura de Solicitud de NotificationCount

Copy

interface NotificationCountGetQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de NotificationCount

Copy

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

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

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

Esta ruta elimina un único NotificationCount por id de usuario. Con SSO, el id de usuario está en el formato <tenant id>:<user id>.

Esto limpiará el conteo de notificaciones no leídas del usuario (la campana roja en el widget de comentarios se desvanecerá y el conteo desaparecerá).

Ejemplo cURL de DELETE NotificationCount

Copy

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

Estructura de Solicitud de Eliminación de NotificationCount

Copy

interface NotificationCountDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Eliminación de NotificationCount

Copy

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

Estructura de notificación

Un objeto Notification representa una notificación para un usuario.

Los objetos Notification se crean automáticamente y no pueden crearse vía la API. También expiran después de un año. Las notificaciones no pueden eliminarse. Sin embargo, pueden actualizarse para establecer viewed a false, y puede consultar por viewed.

Un usuario también puede optar por no recibir notificaciones para un comentario específico estableciendo optedOut en la notificación a true. Puede optar por participar nuevamente estableciéndolo a false.

Hay diferentes tipos de notificaciones - consulte relatedObjectType y type.

Las formas en que se crean las notificaciones es bastante flexible y puede ser activada por muchos escenarios (ver NotificationType).

A día de hoy, la existencia de una Notification no implica realmente que un email se envíe o deba enviarse. Más bien, las notificaciones se usan para el feed de notificaciones e integraciones relacionadas.

La estructura del objeto Notification es la siguiente:

Estructura de Notification

Copy

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

GET /api/v1/notifications

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

Esta ruta devuelve hasta 30 objetos Notification ordenados por createdAt, los más nuevos primero.

Puede filtrar por userId. Con SSO, el id de usuario está en el formato <tenant id>:<user id>.

Ejemplo cURL de Notificaciones No Leídas Para Usuario

Copy

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

Estructura de Solicitud de Notifications

Copy

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

Estructura de Respuesta de Notifications

Copy

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

GET /api/v1/notifications/count

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

Esta ruta devuelve un objeto que contiene el número de notificaciones bajo un parámetro count.

Es más lento que /notification-count/ y el doble del costo de créditos, pero permite filtrar en más dimensiones.

Puede filtrar por los mismos parámetros que el endpoint /notifications como userId. Con SSO, el id de usuario está en el formato <tenant id>:<user id>.

Ejemplo cURL de Conteo de Notificaciones No Leídas Para Usuario

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'

Ejemplo cURL de Conteo de Notificaciones No Leídas Para Usuario Para Página Específica

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'

Estructura de Solicitud de Conteo de Notificaciones

Copy

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

Estructura de Respuesta de Conteo de Notificaciones

Copy

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

PATCH /api/v1/notifications/:id

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

Este endpoint de API proporciona la capacidad de actualizar una Notification por id.

Actualizar una Notification tiene las siguientes restricciones:

Solo puede actualizar los siguientes campos:
- viewed
- optedOut

Ejemplo cURL de PATCH de Notification

Copy

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

Estructura de Solicitud de PATCH de Notification

Copy

interface NotificationPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de PATCH de Notification

Copy

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

Estructura de página

Un objeto Page representa la página a la que pueden pertenecer muchos comentarios. Esta relación se define por urlId.

Una Page almacena información como el título de la página, el conteo de comentarios, y urlId.

La estructura del objeto Page es la siguiente:

Estructura de Page

Copy

interface Page {
    id: string
    urlId: string
    url: string
    title?: string
    createdAt: string
    commentCount: number
    rootCommentCount: number
    /** Setting this to null means all SSO users can see the page. An empty list means it is closed to all users. **/
    accessibleByGroupIds?: string[] | null
    /** Is this page closed for new comments? **/
    isClosed?: boolean
}

GET /api/v1/pages

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

Actualmente solo puede obtener todas las páginas (o una sola página vía /by-url-id) asociadas con su cuenta. Si desea búsqueda más detallada, contáctenos.

Ejemplo cURL de Pages

Copy

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

Estructura de Solicitud de Pages

Copy

interface PagesRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Pages

Copy

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

Consejo Útil

La API de Comment requiere un urlId. Puede llamar primero a la API de Pages, para ver cómo lucen los valores de urlId disponibles para usted.

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

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

Las páginas individuales pueden obtenerse por su correspondiente urlId. Esto puede ser útil para buscar títulos de páginas o conteos de comentarios.

Ejemplo cURL de Page por URL ID

Copy

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

Estructura de Solicitud de Page por URL ID

Copy

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

Estructura de Respuesta de Page por URL ID

Copy

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

Consejo Útil

Recuerde codificar en URI valores como el urlId.

PATCH /api/v1/pages/:id

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

Esta ruta proporciona la capacidad de actualizar una única Page. Los comentarios correspondientes serán actualizados.

Ejemplo cURL de Actualización de Page

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

Estructura de Solicitud de Actualización de Page

Copy

interface PagePatchQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Actualización de Page

Copy

interface PagePatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'missing-id' | 'page-does-not-exist' | 'empty-request' | 'internal' | 'invalid-input' | 'invalid-title' | 'extra-params' | 'accessible-by-group-ids-not-array' | 'too-many-group-ids' | 'group-id-too-large'
    /** Included on failure. **/
    reason?: string
    user?: Page; // We return the complete updated page on success.
}

Nota

Algunos parámetros en el objeto Page se actualizan automáticamente. Estos son los atributos de conteos y título. Los conteos no pueden actualizarse vía la API ya que son valores calculados. El title de la página puede establecerse vía la API, pero sería sobrescrito si el widget de comentarios se usa en una página con el mismo urlId y un título de página diferente.

POST /api/v1/pages

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

Este endpoint de API proporciona la capacidad de crear páginas.

Un caso de uso común es el control de acceso.

Notas:

Si ha comentado en un hilo de comentarios, o llamado a la API para crear un Comment, ¡ya ha creado un objeto Page! Puede intentar obtenerlo vía la ruta de Page /by-url-id, pasando el mismo urlId pasado al widget de comentarios.
La estructura de Page contiene algunos valores calculados. Actualmente, estos son commentCount y rootCommentCount. Se llenan automáticamente y no pueden ser establecidos por la API. Intentar hacerlo causará que la API devuelva un error.

Ejemplo cURL de POST de Page

Copy

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

Estructura de Solicitud de POST de Page

Copy

interface PagePostQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de POST de Page

Copy

interface PagePostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-request' | 'internal' | 'invalid-input' | 'invalid-title' | 'extra-params' | 'accessible-by-group-ids-not-array' | 'too-many-group-ids' | 'group-id-too-large';
    /** Included on failure. **/
    reason?: string
    /** The created page. **/
    page?: Page
}

DELETE /api/v1/pages/:id

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

Esta ruta proporciona la eliminación de una única página por id.

Tenga en cuenta que interactuar con el widget de comentarios para una página con el mismo urlId simplemente recreará la Page sin problemas.

Ejemplo cURL de Eliminación de Page

Copy

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

Estructura de Solicitud de Eliminación de Page

Copy

interface PageDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Eliminación de Page

Copy

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

Estructura de evento webhook pendiente

Un objeto PendingWebhookEvent representa un evento de webhook en cola que está pendiente.

Los objetos PendingWebhookEvent se crean automáticamente y no pueden crearse manualmente vía la API. También expiran después de un año. Pueden eliminarse lo que remueve la tarea de la cola.

Hay diferentes tipos de eventos - consulte eventType (OutboundSyncEventType) y type (OutboundSyncType).

Un caso de uso común para esta API es implementar monitoreo personalizado. Puede querer llamar al endpoint /count periódicamente para sondear el conteo pendiente para filtros dados.

La estructura del objeto PendingWebhookEvent es la siguiente:

Estructura de PendingWebhookEvent

Copy

enum OutboundSyncEventType {
    Create: 0,
    Delete: 1,
    Update: 2
}
enum OutboundSyncType {
    /** WordPress-specific sync task. **/
    WP: 0,
    Webhook: 1
}
interface PendingWebhookEvent {
    id: string
    /** The comment id associated with the event. **/
    commentId: string
    /** The comment object for the event at the time of the event. We started adding these in Nov 2023. **/
    comment: Comment
    /** An external id that may be associated with the comment. **/
    externalId: string | null
    createdAt: Date
    tenantId: string
    attemptCount: number
    /** Set before first attempt, and after every failure. **/
    nextAttemptAt: Date
    /** Whether this is a creation, deletion, or update event... **/
    eventType: OutboundSyncEventType
    /** The type of sync to perform (WordPress, call API, etc). **/
    type: OutboundSyncType
    /** The domain that matched the comment. We use this domain to pick the API key. **/
    domain: string
    /** The last error that occurred. This type is untyped and is a "dump" of whatever happened. Usually it contains an object with statusCode, body, and a headers map. **/
    lastError: object | null
}

GET /api/v1/pending-webhook-events

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

Esta ruta devuelve una lista de eventos de webhook pendientes bajo un parámetro pendingWebhookEvents.

Esta API usa paginación, proporcionada por el parámetro skip. Los PendingWebhookEvents se devuelven en páginas de 100, ordenados por createdAt los más nuevos primero.

Ejemplo cURL de PendingWebhookEvent

Copy

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

Estructura de Solicitud de PendingWebhookEvent

Copy

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

Estructura de Respuesta de PendingWebhookEvent

Copy

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

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

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

Esta ruta devuelve un objeto que contiene el número de eventos de webhook pendientes bajo un parámetro count.

Puede filtrar por los mismos parámetros que el endpoint /pending-webhook-events

Ejemplo cURL de Conteo de PendingWebhookEvent

Copy

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

Estructura de Solicitud de Conteo de PendingWebhookEvent

Copy

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

Estructura de Respuesta de Conteo de PendingWebhookEvent

Copy

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

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

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

Esta ruta permite la eliminación de un único PendingWebhookEvent.

Si necesita una eliminación masiva, llame a la API GET con paginación y luego llame a esta API secuencialmente.

Ejemplo cURL de DELETE PendingWebhookEvent

Copy

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

Estructura de Solicitud de Eliminación de PendingWebhookEvent

Copy

interface PendingWebhookEventDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Eliminación de PendingWebhookEvent

Copy

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

Estructura de usuario SSO

FastComments proporciona una solución SSO fácil de usar. Actualizar la información de un usuario con la integración basada en HMAC es tan simple como hacer que el usuario cargue la página con un payload actualizado.

Sin embargo, puede ser deseable gestionar un usuario fuera de ese flujo, para mejorar la consistencia de su aplicación.

La API de Usuario SSO proporciona una forma de hacer CRUD en objetos que llamamos SSOUsers. Estos objetos son diferentes de los Usuarios regulares y se mantienen separados por seguridad de tipos.

La estructura del objeto SSOUser es la siguiente:

Estructura de 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 // Admin permission - SSO users with this flag are billed as SSO Admins (separate from regular SSO users)
    isAdminAdmin?: boolean // Admin permission - SSO users with this flag are billed as SSO Admins (separate from regular SSO users)
    isCommentModeratorAdmin?: boolean // Moderator permission - SSO users with this flag are billed as SSO Moderators (separate from regular SSO users)
    /** If null, Access Control will not be applied to the user. If an empty list, this user will not be able to see any pages or @mention other users. **/
    groupIds?: string[] | null
    createdFromSimpleSSO?: boolean
    /** Don't let other users see this user's activity, including comments, on their profile. Default is true to provide secure profiles by default. **/
    isProfileActivityPrivate?: boolean
    /** Don't let other users leave comments on the user's profile, or see existing profile comments. Default false. **/
    isProfileCommentsPrivate?: boolean
    /** Don't let other users send direct messages to this user. Default false. **/
    isProfileDMDisabled?: boolean
    karma?: number
    /** Optional configuration for user badges. **/
    badgeConfig?: {
        /** Array of badge IDs to assign to the user. Limited to 30 badges. Order is respected. **/
        badgeIds: string[]
        /** If true, replaces all existing displayed badges with the provided ones. If false, adds to existing badges. **/
        override?: boolean
        /** If true, updates badge display properties from tenant configuration. **/
        update?: boolean
    }
}

Facturación para Usuarios SSO

Los usuarios SSO se facturan de manera diferente según sus banderas de permisos:

Usuarios SSO Regulares: Los usuarios sin permisos de administrador o moderador se facturan como usuarios SSO regulares
Administradores SSO: Los usuarios con banderas isAccountOwner o isAdminAdmin se facturan por separado como Administradores SSO (misma tarifa que los administradores de inquilino regulares)
Moderadores SSO: Los usuarios con bandera isCommentModeratorAdmin se facturan por separado como Moderadores SSO (misma tarifa que los moderadores regulares)

Importante: Para prevenir doble facturación, el sistema automáticamente deduplica usuarios SSO contra usuarios de inquilino regulares y moderadores por dirección de email. Si un usuario SSO tiene el mismo email que un usuario de inquilino regular o moderador, no serán facturados dos veces.

Control de Acceso

Los usuarios pueden dividirse en grupos. Esto es para lo que es el campo groupIds, y es opcional.

@Menciones

Por defecto @mentions usará username para buscar otros usuarios sso cuando se escribe el carácter @. Si se usa displayName, entonces los resultados que coincidan con username serán ignorados cuando haya una coincidencia para displayName, y los resultados de búsqueda de @mention usarán displayName.

Suscripciones

Con FastComments, los usuarios pueden suscribirse a una página haciendo clic en el icono de campana en el widget de comentarios y haciendo clic en Suscribirse.

Con un usuario regular, les enviamos emails de notificación basados en sus configuraciones de notificación.

Con Usuarios SSO, dividimos esto para compatibilidad hacia atrás. Los usuarios solo recibirán estos emails de notificación de suscripción adicionales si establece optedInSubscriptionNotifications a true.

Insignias

Puede asignar insignias a usuarios SSO usando la propiedad badgeConfig. Las insignias son indicadores visuales que aparecen junto al nombre de un usuario en los comentarios.

badgeIds - Un array de IDs de insignias para asignar al usuario. Estos deben ser IDs de insignias válidos creados en su cuenta de FastComments. Limitado a 30 insignias.
override - Si es verdadero, todas las insignias existentes mostradas en comentarios serán reemplazadas con las proporcionadas. Si es falso u omitido, las insignias proporcionadas se agregarán a cualquier insignia existente.
update - Si es verdadero, las propiedades de visualización de insignias se actualizarán desde la configuración del inquilino cada vez que el usuario inicie sesión.

GET /api/v1/sso-users

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

Esta ruta devuelve Usuarios SSO en páginas de 100. La paginación se proporciona por el parámetro skip. Los usuarios están ordenados por su signUpDate e id.

Ejemplo cURL de SSOUsers

Copy

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

Estructura de Solicitud de SSOUsers

Copy

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

Estructura de Respuesta de SSOUsers

Copy

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

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

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

Esta ruta devuelve un único usuario SSO por su id.

Ejemplo cURL de SSOUser por ID

Copy

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

Estructura de Solicitud de SSOUser

Copy

interface SSOUserRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de SSOUser

Copy

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

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

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

Esta ruta devuelve un único usuario SSO por su email.

Ejemplo cURL de SSOUser por Email

Copy

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

Estructura de Solicitud de SSOUser

Copy

interface SSOUserRequestByEmailQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de SSOUser

Copy

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

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

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

Esta ruta proporciona la capacidad de actualizar un único usuario SSO.

Ejemplo cURL de Actualización de SSOUser

Copy

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

Estructura de Solicitud de Actualización de SSOUser

Copy

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

Estructura de Respuesta de Actualización de SSOUser

Copy

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

POST /api/v1/sso-users

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

Esta ruta proporciona la creación de un único usuario SSO.

Intentar crear dos usuarios con el mismo ID resultará en un error.

Ejemplo cURL de Creación de SSOUser

Copy

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

En este ejemplo especificamos groupIds para control de acceso, pero esto es opcional.

Estructura de Solicitud de Creación de SSOUser

Copy

interface SSOUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Creación de SSOUser

Copy

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

Nota de Integración

Los datos pasados por la API pueden ser sobrescritos simplemente pasando un payload de Usuario SSO HMAC diferente. Por ejemplo, si establece un nombre de usuario vía la API, pero luego pasa uno diferente vía el flujo SSO al cargar la página, actualizaremos automáticamente su nombre de usuario.

No actualizaremos parámetros de usuario en este flujo a menos que los especifique explícitamente o los establezca a null (no undefined).

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

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

Esta ruta proporciona la capacidad de actualizar un único usuario SSO.

Ejemplo cURL de Actualización de SSOUser

Copy

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

En este ejemplo especificamos groupIds para control de acceso, pero esto es opcional.

Estructura de Solicitud de Actualización de SSOUser

Copy

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

Estructura de Respuesta de Actualización de SSOUser

Copy

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

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

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

Esta ruta proporciona la eliminación de un único usuario SSO por su id.

Tenga en cuenta que cargar el widget de comentarios nuevamente con un payload para este usuario simplemente recreará el usuario sin problemas.

Eliminar los comentarios del usuario es posible vía el parámetro de consulta deleteComments. Tenga en cuenta que si esto es verdadero:

Todos los comentarios del usuario serán eliminados en vivo.
Todos los comentarios hijos (ahora huérfanos) serán eliminados o anonimizados basándose en la configuración de página asociada de cada comentario. Por ejemplo si el modo de eliminación de hilo es "anonimizar", entonces las respuestas permanecerán, y los comentarios del usuario serán anonimizados. Esto solo aplica cuando commentDeleteMode es Remove (el valor predeterminado).
El creditsCost se convierte en 2.

Comentarios Anonimizados

Puede retener los comentarios del usuario pero simplemente anonimizarlos estableciendo commentDeleteMode=1.

Si los comentarios del usuario son anonimizados entonces los siguientes valores se establecen a null:

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

isDeleted e isDeletedUser se establecen a true.

Al renderizar, el widget de comentarios usará DELETED_USER_PLACEHOLDER (predeterminado: "[deleted]") para el nombre del usuario y DELETED_CONTENT_PLACEHOLDER para el comentario. Estos pueden personalizarse vía la UI de Personalización del Widget.

Ejemplos

Ejemplo cURL de Eliminación de SSOUser

Copy

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

Estructura de Solicitud de Eliminación de SSOUser

Copy

enum SSOUserCommentDeleteMode {
    Remove = 0, // default
    Anonymize = 1
}
interface SSOUsersDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** You can set this to true to also delete the user's comments. This will double the credit cost. **/
    deleteComments?: 'true' | 'false'
    /** You can set this as desired to determine how to handle the user's comments. **/
    commentDeleteMode?: SSOUserCommentDeleteMode
}

Estructura de Respuesta de Eliminación de SSOUser

Copy

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

Estructura de suscripción

Un objeto Subscription representa una suscripción para un usuario.

Los objetos Subscription se crean cuando un usuario hace clic en la campana de notificación en el widget de comentarios y hace clic en "Suscribirse a esta página".

Las suscripciones también pueden crearse vía la API.

Tener un objeto Subscription causa que se generen objetos Notification, y se envíen emails, cuando se dejan nuevos comentarios en la raíz de la página asociada para la cual es la Subscription. El envío de emails depende del tipo de usuario. Para usuarios regulares esto depende de optedInNotifications. Para Usuarios SSO esto depende de optedInSubscriptionNotifications. Tenga en cuenta que algunas aplicaciones pueden no tener el concepto de una página accesible por web, en cuyo caso simplemente establezca urlId al id del elemento al que se está suscribiendo (mismo valor para urlId que pasaría al widget de comentarios).

La estructura del objeto Subscription es la siguiente:

Estructura de Subscription

Copy

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

GET /api/v1/subscriptions/:id

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

Esta ruta devuelve hasta 30 objetos Subscription ordenados por createdAt, los más nuevos primero.

Puede filtrar por userId. Con SSO, el id de usuario está en el formato <tenant id>:<user id>.

Ejemplo cURL de Subscriptions Para Usuario

Copy

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

Estructura de Solicitud de Subscriptions

Copy

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

Estructura de Respuesta de Subscriptions

Copy

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

POST /api/v1/subscriptions

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

Este endpoint de API proporciona la capacidad de crear una Subscription. Tenga en cuenta que un usuario solo puede tener una suscripción por página, ya que más es redundante, e intentar crear más de una suscripción para el mismo usuario para la misma página resultará en un error.

Crear una suscripción resultará en objetos Notification siendo creados cuando se deje un nuevo comentario en la raíz del urlId suscrito (cuando parentId del comentario es null).

Ejemplo cURL de POST de Subscription

Copy

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

Estructura de Solicitud de POST de Subscription

Copy

interface SubscriptionPostQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de POST de Subscription

Copy

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

DELETE /api/v1/subscriptions/:id

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

Esta ruta elimina un único objeto Subscription por id.

Ejemplo cURL de Eliminación de Subscription

Copy

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

Estructura de Solicitud de Eliminación de Subscription

Copy

interface SubscriptionsDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Eliminación de Subscription

Copy

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

Estructura de uso diario del tenant

Un objeto TenantDailyUsage representa el uso para un inquilino en un día dado. Si no hubo actividad para un inquilino dado en un día dado, ese día no tendrá un objeto TenantDailyUsage.

El objeto TenantDailyUsage no es en tiempo real y puede estar minutos detrás del uso real.

La estructura del objeto TenantDailyUsage es la siguiente:

Estructura de TenantDailyUsage

Copy

export interface TenantDailyUsage {
    yearNumber: number
    monthNumber: number
    dayNumber: number
    commentFetchCount?: number
    commentCreateCount?: number
    conversationCreateCount?: number
    voteCount?: number
    accountCreatedCount?: number
    userMentionSearch?: number
    hashTagSearch?: number
    gifSearchTrending?: number
    gifSearch?: number
    apiCreditsUsed?: number
    createdAt: string
    billed: boolean
    /** Ignored for billing. **/
    ignored: boolean
}

GET /api/v1/tenant-daily-usage

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

Esta ruta permite buscar el uso de un inquilino por año, mes y día. Pueden devolverse hasta 365 objetos, y el costo es 1 crédito de api por cada 10 objetos.

Los objetos de respuesta están ordenados por la fecha en que fueron creados (los más antiguos primero).

Ejemplo cURL de Búsqueda de TenantDailyUsage

Copy

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

Estructura de Solicitud de TenantDailyUsage

Copy

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

Estructura de Respuesta de TenantDailyUsage

Copy

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

Estructura de tenant

El Tenant define un cliente de FastComments.com. Pueden ser creados a través de la API por inquilinos con acceso de marca blanca. Los inquilinos de marca blanca no pueden crear otros inquilinos de marca blanca (solo se permite un nivel de anidación).

La estructura del objeto Tenant es la siguiente:

Estructura de Tenant

Copy

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

GET /api/v1/tenants/:id

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

Esta ruta devuelve un único Tenant por id.

Ejemplo cURL de Tenant por ID

Copy

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

Estructura de Solicitud de Tenant

Copy

interface TenantByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Tenant

Copy

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

GET /api/v1/tenants

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

Esta API devuelve inquilinos que son gestionados por su inquilino.

La paginación se proporciona mediante el parámetro de consulta skip. Los inquilinos se devuelven en páginas de 100, ordenados por signUpDate e id.

El costo se basa en el número de inquilinos devueltos, costando 1 crédito por cada 10 inquilinos devueltos.

Ejemplo cURL de Tenant

Copy

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

Puede definir parámetros meta en los objetos Tenant y consultar inquilinos coincidentes. Por ejemplo, para la clave someKey y el valor meta some-value, podemos construir un objeto JSON con este par clave/valor y luego codificarlo como URI como parámetro de consulta para filtrar:

Ejemplo cURL de Consulta de Tenant por Meta

Copy

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

Estructura de Solicitud de Tenant

Copy

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

Estructura de Respuesta de Tenant

Copy

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

POST /api/v1/tenants

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

Esta ruta proporciona la capacidad de agregar un único Tenant.

Crear un Tenant tiene las siguientes restricciones:

Se requiere un name.
Se requiere domainConfiguration.
Los siguientes valores no pueden ser proporcionados al crear un Tenant:
- hasFlexPricing
- lastBillingIssueReminderDate
- flexLastBilledAmount
El signUpDate no puede estar en el futuro.
El name no puede tener más de 200 caracteres.
El email no puede tener más de 300 caracteres.
El email debe ser único en todos los inquilinos de FastComments.com.
No puede crear inquilinos si el inquilino padre no tiene un TenantPackage válido definido.
- Si su inquilino fue creado a través de FastComments.com, esto no debería ser un problema.
No puede crear más inquilinos de los definidos en maxWhiteLabeledTenants en su paquete.
Debe especificar el parámetro de consulta tenantId que es el id de su inquilino padre con marca blanca habilitada.

Podemos crear un Tenant con solo unos pocos parámetros:

Ejemplo cURL de Creación de Tenant

Copy

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

Estructura de Solicitud de Creación de Tenant

Copy

interface TenantPostQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Creación de Tenant

Copy

interface TenantPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' | 'unexpected-param' | 'sign-up-date-in-future' | 'payment-frequency-invalid' | 'cannot-change-payment-frequency' | 'name-invalid' | 'email-invalid' | 'email-taken' | 'no-package' | 'invalid-package' | 'unauthorized' | 'tenant-limit-reached' | 'cannot-move-tenant' | 'cannot-change-package' | 'invalid-billing-info'
    /** Included on failure. **/
    reason?: string
    tenant?: Tenant; // We return the complete created tenant on success.
}

PATCH /api/v1/tenants/:id

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

Este endpoint de API proporciona la capacidad de actualizar un Tenant por id.

Actualizar un Tenant tiene las siguientes restricciones:

Los siguientes valores no pueden ser actualizados:
- hasFlexPricing
- lastBillingIssueReminderDate
- flexLastBilledAmount
- managedByTenantId
El signUpDate no puede estar en el futuro.
El name no puede tener más de 200 caracteres.
El email no puede tener más de 300 caracteres.
El email debe ser único en todos los inquilinos de FastComments.com.
Al establecer billingInfoValid en true, se debe proporcionar billingInfo en la misma solicitud.
No puede actualizar el packageId asociado con su propio inquilino.
No puede actualizar la paymentFrequency asociada con su propio inquilino.

Ejemplo cURL de PATCH de Tenant

Copy

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

Estructura de Solicitud de PATCH de Tenant

Copy

interface TenantPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de PATCH de Tenant

Copy

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

DELETE /api/v1/tenants/:id

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

Esta ruta proporciona la eliminación de un Tenant y todos los datos asociados (usuarios, comentarios, etc) por id.

Las siguientes restricciones existen alrededor de eliminar inquilinos:

El inquilino debe ser el suyo propio, o un inquilino de marca blanca que usted gestiona.
El parámetro de consulta sure debe establecerse a true.

Ejemplo cURL de Eliminación de Tenant

Copy

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

Estructura de Solicitud de Eliminación de Tenant

Copy

interface TenantDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Eliminación de Tenant

Copy

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

Estructura de paquete de tenant

El TenantPackage define la información del paquete disponible para un Tenant. Un inquilino puede tener muchos paquetes disponibles, pero solo uno en uso en un momento dado.

Un Tenant no puede ser utilizado para ningún producto hasta que su packageId apunte a un TenantPackage válido.

Hay dos tipos de objetos TenantPackage:

Paquetes de precio fijo - donde hasFlexPricing es falso.
Precios flexibles - donde hasFlexPricing es verdadero.

En ambos casos se definen límites en la cuenta que usa el paquete, sin embargo con Flex el inquilino paga un precio base más lo que usó, definido por los parámetros flex*.

Un inquilino puede tener múltiples paquetes de inquilino y tener la capacidad de cambiar el paquete ellos mismos desde la Página de Información de Facturación.

Si usted manejará la facturación de los inquilinos por su cuenta, aún necesitará definir un paquete para cada inquilino para definir sus límites. Simplemente establezca billingHandledExternally en true en el Tenant y ellos no podrán cambiar su información de facturación, o paquete activo, por sí mismos.

No puede crear paquetes con límites más altos que el inquilino padre.

La estructura del objeto TenantPackage es la siguiente:

Estructura de 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 // Costo por usuario SSO regular (sin permisos de admin/moderador)
    flexSSOUserUnit?: null
    flexAPICreditCostCents?: null
    flexAPICreditUnit?: null
    flexModeratorCostCents?: null
    flexModeratorUnit?: null
    flexAdminCostCents?: null
    flexAdminUnit?: null
    flexDomainCostCents?: null
    flexDomainUnit?: null
    flexSSOAdminCostCents?: null // Costo por usuario SSO con permisos de administrador (flags isAccountOwner o isAdminAdmin)
    flexSSOAdminUnit?: null
    flexSSOModeratorCostCents?: null // Costo por usuario SSO con permisos de moderador (flag isCommentModeratorAdmin)
    flexSSOModeratorUnit?: null
    flexMinimumCostCents?: null
}

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

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

Esta ruta devuelve un único Paquete de Inquilino por id.

Ejemplo cURL de TenantPackage por ID

Copy

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

Estructura de Solicitud de TenantPackage

Copy

interface TenantPackageByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de TenantPackage

Copy

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

GET /api/v1/tenant-packages

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

Esta API utiliza paginación, proporcionada por el parámetro de consulta skip. Los TenantPackages se devuelven en páginas de 100, ordenados por createdAt e id.

El costo se basa en el número de paquetes de inquilino devueltos, costando 1 crédito por cada 10 paquetes de inquilino devueltos.

Ejemplo cURL de TenantPackage

Copy

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

Estructura de Solicitud de TenantPackage

Copy

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

Estructura de Respuesta de TenantPackage

Copy

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

POST /api/v1/tenant-packages

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

Esta ruta proporciona la capacidad de agregar un único TenantPackage.

Crear un TenantPackage tiene las siguientes restricciones:

Los siguientes parámetros son requeridos:
- name
- tenantId
- monthlyCostUSD - Puede ser null.
- yearlyCostUSD - Puede ser null.
- maxMonthlyPageLoads
- maxMonthlyAPICredits
- maxMonthlyComments
- maxConcurrentUsers
- maxTenantUsers
- maxSSOUsers
- maxModerators
- maxDomains
- hasDebranding
- forWhoText
- featureTaglines
- hasFlexPricing - Si es verdadero, entonces todos los parámetros flex* son requeridos.
El name no puede tener más de 50 caracteres.
Cada elemento de forWhoText no puede tener más de 200 caracteres.
Cada elemento de featureTaglines no puede tener más de 100 caracteres.
El TenantPackage debe ser "más pequeño" que el inquilino padre. Por ejemplo, todos los parámetros max* deben tener valores más bajos que el inquilino padre.
Un inquilino de marca blanca puede tener un máximo de cinco paquetes.
Solo inquilinos con acceso de marca blanca pueden crear un TenantPackage.
No puede agregar paquetes a su propio inquilino. :)

Podemos crear un TenantPackage de la siguiente manera:

Ejemplo cURL de Creación de TenantPackage vía Email

Copy

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

Estructura de Solicitud de Creación de TenantPackage

Copy

interface TenantPackagePostQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Creación de TenantPackage

Copy

interface TenantPackagePostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' 'white-labeling-not-allowed' | 'name-too-long' | 'for-who-text-too-long' | 'feature-tag-lines-too-long' | 'no-package' | 'invalid-package' | 'unauthorized' | 'child-tenant-too-large' | 'flex-param-missing' | 'unexpected-flex-param' | 'package-limit-reached' | 'flex-param-missing' | 'unexpected-flex-param'
    /** Included on failure. **/
    reason?: string
    tenantPackage?: TenantPackage; // We return the complete created tenant package on success.
}

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

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

Este endpoint de API proporciona la capacidad de actualizar un TenantPackage por id.

Actualizar un TenantPackage tiene las siguientes restricciones:

Si está estableciendo hasFlexPricing a verdadero, entonces todos los parámetros flex* son requeridos en esa misma solicitud.
El name no puede tener más de 50 caracteres.
Cada elemento de forWhoText no puede tener más de 200 caracteres.
Cada elemento de featureTaglines no puede tener más de 100 caracteres.
El TenantPackage debe ser "más pequeño" que el inquilino padre. Por ejemplo, todos los parámetros max* deben tener valores más bajos que el inquilino padre.
No puede cambiar el tenantId asociado con un TenantPackage.

Ejemplo cURL de PATCH de TenantPackage

Copy

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

Estructura de Solicitud de PATCH de TenantPackage

Copy

interface TenantPackagePatchQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de PATCH de TenantPackage

Copy

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

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

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

Esta ruta proporciona la eliminación de un TenantPackage por id.

No puede eliminar un TenantPackage que está en uso (el packageId de un inquilino apunta al paquete). Actualice el Tenant primero.

Ejemplo cURL de Eliminación de TenantPackage

Copy

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

Estructura de Solicitud de Eliminación de TenantPackage

Copy

interface TenantPackageDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Eliminación de TenantPackage

Copy

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

Estructura de usuario del tenant

El TenantUser define un User que es gestionado por un inquilino específico. Su cuenta está bajo control completo del inquilino al que están asociados, y su cuenta puede ser actualizada o eliminada a través de la UI o API.

Los usuarios de inquilino pueden ser administradores con todos los permisos y acceso al Tenant, o pueden estar limitados a permisos específicos para moderar comentarios, acceder a claves de API, etc.

La estructura del objeto TenantUser es la siguiente:

Estructura de TenantUser

Copy

/** This is for notifications. **/
export enum UserDigestEmailFrequency {
    Disabled = -1,
    Daily = 0,
    Weekly = 1,
    Monthly = 2
}
export interface TenantUser {
    id: string
    tenantId: string
    username: string
    /** A link to the commenter's blog, for example. **/
    websiteUrl?: string
    email: string
    signUpDate: number
    createdFromUrlId: string
    createdFromTenantId: string
    verified: boolean
    loginCount: number
    optedInNotifications: boolean
    optedInTenantNotifications: boolean
    hideAccountCode: boolean
    avatarSrc?: string
    /** Does the user receive help requests from commenters? **/
    isHelpRequestAdmin: boolean
    isAccountOwner: boolean
    isAdminAdmin: boolean
    isBillingAdmin: boolean
    isAnalyticsAdmin: boolean
    isCustomizationAdmin: boolean
    isManageDataAdmin: boolean
    isCommentModeratorAdmin: boolean
    isAPIAdmin: boolean
    moderatorIds: string[]
    locale: FastCommentsLocale
    digestEmailFrequency: UserDigestEmailFrequency
    lastLoginDate: string
    displayLabel?: string
    karma?: number
}

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

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

Esta ruta devuelve un único TenantUser por id.

Ejemplo cURL de TenantUser por ID

Copy

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

Estructura de Solicitud de TenantUser

Copy

interface TenantUserByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de TenantUser

Copy

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

GET /api/v1/tenant-users

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

Esta API utiliza paginación, proporcionada por el parámetro de consulta skip. Los TenantUsers se devuelven en páginas de 100, ordenados por signUpDate, username e id.

El costo se basa en el número de usuarios de inquilino devueltos, costando 1 crédito por cada 10 usuarios de inquilino devueltos.

Ejemplo cURL de TenantUser

Copy

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

Estructura de Solicitud de TenantUser

Copy

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

Estructura de Respuesta de TenantUser

Copy

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

POST /api/v1/tenant-users

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

Esta ruta proporciona la capacidad de agregar un único TenantUser.

Crear un TenantUser tiene las siguientes restricciones:

Se requiere un username.
Se requiere un email.
El signUpDate no puede estar en el futuro.
El locale debe estar en la lista de Locales Soportados.
El username debe ser único en todo FastComments.com. Si esto es un problema, sugerimos usar SSO en su lugar.
El email debe ser único en todo FastComments.com. Si esto es un problema, sugerimos usar SSO en su lugar.
No puede crear más usuarios de inquilino de los definidos en maxTenantUsers en su paquete.

Podemos crear un TenantUser de la siguiente manera

Ejemplo cURL de Creación de TenantUser

Copy

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

Estructura de Solicitud de Creación de TenantUser

Copy

interface TenantUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Creación de TenantUser

Copy

interface TenantUserPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'username-required' | 'email-required' | 'sign-up-date-in-future' | 'unsupported-locale' | 'unauthorized' | 'username-taken' | 'email-taken' | 'tenant-user-limit-reached'
    /** Included on failure. **/
    reason?: string
    tenantUser?: TenantUser; // We return the complete created tenant user on success.
}

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

Esta ruta proporciona la capacidad de enviar un enlace de inicio de sesión a un único TenantUser.

Útil al crear usuarios por lotes sin tener que instruirles sobre cómo iniciar sesión en FastComments.com. Esto simplemente les enviará un "enlace mágico" para iniciar sesión que expira después de 30 días.

Las siguientes restricciones existen para enviar un enlace de inicio de sesión a un TenantUser:

El TenantUser ya debe existir.
Debe tener acceso para administrar el Tenant al que pertenece el TenantUser.

Podemos enviar un enlace de inicio de sesión a un TenantUser de la siguiente manera:

Ejemplo cURL de Enlace de Inicio de Sesión de TenantUser

Copy

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

Esto enviará un email como Bob en TenantName te está invitando a ser moderador...

Estructura de Solicitud de Enlace de Inicio de Sesión de TenantUser

Copy

interface TenantUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Enlace de Inicio de Sesión de TenantUser

Copy

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

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

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

Esta ruta proporciona la capacidad de actualizar un único TenantUser.

Actualizar un TenantUser tiene las siguientes restricciones:

El signUpDate no puede estar en el futuro.
El locale debe estar en la lista de Locales Soportados.
El username debe ser único en todo FastComments.com. Si esto es un problema, sugerimos usar SSO en su lugar.
El email debe ser único en todo FastComments.com. Si esto es un problema, sugerimos usar SSO en su lugar.
No puede actualizar el tenantId de un usuario.

Podemos crear un TenantUser de la siguiente manera

Ejemplo cURL de Actualización de TenantUser

Copy

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

Estructura de Solicitud de Actualización de TenantUser

Copy

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

Estructura de Respuesta de Actualización de TenantUser

Copy

interface TenantUserPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'sign-up-date-in-future' | 'unsupported-locale' | 'unauthorized' | 'username-taken' | 'email-taken' | 'unauthorized' | 'no-package' | 'invalid-package' | 'tenant-user-limit-reached' | 'user-does-not-exist'
    /** Included on failure. **/
    reason?: string
}

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

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

Esta ruta proporciona la eliminación de un TenantUser por id.

Es posible eliminar los comentarios del usuario mediante el parámetro de consulta deleteComments. Tenga en cuenta que si esto es verdadero:

Todos los comentarios del usuario serán eliminados en vivo.
Todos los comentarios hijos (ahora huérfanos) serán eliminados o anonimizados según la configuración de página asociada a cada comentario. Por ejemplo, si el modo de eliminación de hilo es "anonimizar", entonces las respuestas permanecerán, y los comentarios del usuario serán anonimizados. Esto solo aplica cuando commentDeleteMode es Remove (el valor predeterminado).
El creditsCost se convierte en 2.

Comentarios Anonimizados

Puede retener los comentarios del usuario pero simplemente anonimizarlos estableciendo commentDeleteMode=1.

Si los comentarios del usuario son anonimizados, los siguientes valores se establecen en null:

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

isDeleted e isDeletedUser se establecen en true.

Al renderizar, el widget de comentarios usará DELETED_USER_PLACEHOLDER (predeterminado: "[deleted]") para el nombre del usuario y DELETED_CONTENT_PLACEHOLDER para el comentario. Estos pueden ser personalizados a través de la UI de Personalización del Widget.

Ejemplos

Ejemplo cURL de Eliminación de TenantUser

Copy

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

Estructura de Solicitud de Eliminación de TenantUser

Copy

enum TenantUserCommentDeleteMode {
    Remove = 0, // default
    Anonymize = 1
}
interface TenantUserDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** You can set this to true to also delete the user's comments. This will double the credit cost. **/
    deleteComments?: 'true' | 'false'
    /** You can set this as desired to determine how to handle the user's comments. **/
    commentDeleteMode?: TenantUserCommentDeleteMode
}

Estructura de Respuesta de Eliminación de TenantUser

Copy

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

Estructura de usuario

User es un objeto que representa el denominador más común de todos los usuarios.

Tenga en cuenta que en FastComments tenemos varios casos de uso diferentes para usuarios:

SSO Seguro
SSO Simple
Usuarios de Inquilino (Por ejemplo: Administradores)
Comentaristas

Esta API es para Comentaristas y usuarios creados a través de SSO Simple. Básicamente, cualquier usuario creado a través de su sitio puede ser accedido a través de esta API. Los Usuarios de Inquilino también pueden ser obtenidos de esta manera, pero obtendrá más información interactuando con la API /tenant-users/.

Para SSO Seguro por favor use la API /sso-users/.

No puede actualizar estos tipos de usuarios. Ellos crearon su cuenta a través de su sitio, por lo que proporcionamos acceso básico de solo lectura, pero no puede realizar cambios. Si desea tener este tipo de flujo - necesita configurar SSO Seguro.

La estructura del objeto User es la siguiente:

Estructura de User

Copy

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

GET /api/v1/users/:id

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

Esta ruta devuelve un único User por id.

Ejemplo cURL de User por ID

Copy

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

Estructura de Solicitud de User

Copy

interface UserByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de User

Copy

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

Estructura de voto

Un objeto Vote representa un voto dejado por un usuario.

La relación entre comentarios y votos se define mediante commentId.

La estructura del objeto Vote es la siguiente:

Estructura de 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

Los votos deben ser obtenidos por urlId.

Tipos de Votos

Hay tres tipos de votos:

Votos Autenticados, que se aplican al comentario correspondiente. Puede crear estos a través de esta API.
Votos Autenticados, que están pendientes de verificación, y por lo tanto aún no se aplican al comentario. Estos se crean cuando un usuario usa el mecanismo de iniciar sesión para votar de FastComments.com.
Votos Anónimos, que se aplican al comentario correspondiente. Estos se crean junto con los comentarios anónimos.

Estos se devuelven en listas separadas en la API para reducir la confusión.

Ejemplo cURL de Votes

Copy

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

Estructura de Solicitud de Votes

Copy

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

Estructura de Respuesta de Votes

Copy

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

Notas sobre Votos Anónimos

Tenga en cuenta que los votos anónimos creados a través de esta API aparecerán en la lista appliedAuthorizedVotes. Se consideran autorizados ya que fueron creados a través de la API con una clave de API.

La estructura appliedAnonymousVotes es para votos creados sin un email, clave de API, etc.

GET /api/v1/votes/for-user

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

Permite obtener votos dejados por un usuario en un urlId dado. Toma un userId que puede ser cualquier usuario de FastComments.com o SSO User.

Esto es útil si desea mostrar si un usuario ha votado en un comentario. Al obtener comentarios, simplemente llame a esta API al mismo tiempo para el usuario con el mismo urlId.

Si está usando votación anónima, entonces querrá pasar anonUserId en su lugar.

Ejemplo cURL de Votes para Usuario

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'

Ejemplo cURL de Votes para Usuario Anónimo

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'

Tenga en cuenta que los votos anónimos aparecerán en la lista appliedAuthorizedVotes. Se consideran autorizados ya que fueron creados a través de la API con una clave de API.

Estructura de Solicitud de Votes para Usuario

Copy

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

Estructura de Respuesta de Votes para Usuario

Copy

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

POST /api/v1/votes

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

Esta ruta proporciona la capacidad de agregar un único Vote autorizado. Los votos pueden ser up (+1) o down (-1).

Ejemplo cURL de Creación de Vote

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'

Ejemplo cURL de Creación de Vote Anónimo

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'

Estructura de Solicitud de Creación de Vote

Copy

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

Estructura de Respuesta de Creación de Vote

Copy

interface VotePostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-user-id' | 'invalid-user-id' | 'invalid-comment-id' | 'invalid-direction' | 'duplicate' | 'voting-disabled'
    /** Included on failure. **/
    reason?: string
    voteId?: string
}

Creación de Votos Anónimos

Los votos anónimos pueden ser creados estableciendo anonUserId en los parámetros de consulta en lugar de userId.

Este id no tiene que corresponder a un objeto de usuario en ningún lugar (de ahí anónimo). Es simplemente un identificador para la sesión, para que pueda obtener los votos nuevamente en la misma sesión, para verificar si un comentario ha sido votado.

Si no tiene algo como "sesiones anónimas" como FastComments - simplemente puede establecer esto en un ID aleatorio, como un UUID (aunque apreciamos identificadores más pequeños para ahorrar espacio).

Otras Notas

Esta API obedece la configuración a nivel de inquilino. Por ejemplo, si deshabilita la votación para una página determinada, e intenta crear un voto a través de la API, fallará con el código de error voting-disabled.
Esta API es en vivo por defecto.
Esta API actualizará los votes del Comment correspondiente.

DELETE /api/v1/votes/:id

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

Esta ruta proporciona la capacidad de eliminar un único Vote.

Ejemplo cURL de Eliminación de Vote

Copy

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

Estructura de Solicitud de Eliminación de Vote

Copy

interface VoteDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Eliminación de Vote

Copy

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

Notas:

Esta API obedece la configuración a nivel de inquilino. Por ejemplo, si deshabilita la votación para una página determinada, e intenta crear un voto a través de la API, fallará con el código de error voting-disabled.
Esta API es en vivo por defecto.
Esta API actualizará los votes del Comment correspondiente.

Estructura de configuración de dominio

Un objeto DomainConfig representa la configuración para un dominio de un inquilino.

La estructura del objeto DomainConfig es la siguiente:

Estructura de Configuración de Dominio

Copy

interface DomainConfig {
    /** A domain, not a URL, like "fastcomments.com" or "www.example.com". Subdomain may be included if limiting to a subdomain is desired. Max 1000 characters. **/
    domain: string
    /** The From-Name used when sending emails. **/
    emailFromName?: string
    /** The From-Email used when sending emails. Ensure SPF is setup to allow mail.fastcomments.com to send emails as the domain used in this attribute. **/
    emailFromEmail?: string
    /** READONLY. When the object was created. **/
    createdAt: string
    /** The logo related to this domain. Used in emails. Use HTTPS. **/
    logoSrc?: string
    /** A smaller logo related to this domain. Use HTTPS. **/
    logoSrc100px?: string
    /** SSO ONLY. The URL used in the footer of every email sent. Supports a "[userId]" variable. **/
    footerUnsubscribeURL?: string
    /** SSO ONLY. The headers used in of every email sent. Useful for example for setting unsubscribe related headers to improve delivery. The List-Unsubscribe entry in this Record, if it exists, supports a "[userId]" variable. **/
    emailHeaders?: Record<string, string>
    /** Disable all unsubscribe links. Not recommended, may hurt delivery rates. **/
    disableUnsubscribeLinks?: boolean
    /** DKIM Configuration. **/
    dkim?: DomainConfigDKIM
}

Estructura de Configuración DKIM

Copy

interface DomainConfigDKIM {
    /** The domain name in your DKIM record. **/
    domainName: string
    /** The DKIM key selector to use. **/
    keySelector: string
    /** Your private key. Start with -----BEGIN PRIVATE KEY----- and end with -----END PRIVATE KEY----- **/
    privateKey: string
}

Para Autenticación

La Configuración de Dominio se usa para determinar qué sitios pueden alojar el widget de FastComments para su cuenta. Esta es una forma básica de autenticación, lo que significa que agregar o eliminar cualquier Configuración de Dominio puede impactar la disponibilidad de su instalación de FastComments en producción.

No elimine ni actualice la propiedad domain de una Domain Config para un dominio que está actualmente en uso a menos que deshabilitar ese dominio sea intencional.

Esto tiene el mismo comportamiento que eliminar un dominio desde /auth/my-account/configure-domains.

También tenga en cuenta que eliminar un dominio desde la UI de Mis Dominios eliminará cualquier configuración correspondiente para ese dominio que pueda haber sido agregada a través de esta UI.

Para Personalización de Email

El enlace de cancelación de suscripción en el pie de página del email, y la función de cancelación de suscripción con un clic ofrecida por muchos clientes de correo electrónico, se pueden configurar a través de esta API definiendo footerUnsubscribeURL y emailHeaders, respectivamente.

Para DKIM

Después de definir sus registros DNS de DKIM, simplemente actualice el DomainConfig con su configuración DKIM usando la estructura definida.

GET /api/v1/domain-configs

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

Esta API proporciona la capacidad de obtener todos los objetos DomainConfig para un inquilino.

Ejemplo cURL de GET de DomainConfig

Copy

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

Estructura de Solicitud de GET de DomainConfig

Copy

interface GetDomainConfigsRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de GET de DomainConfig

Copy

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

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

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

Los DomainConfigs individuales pueden obtenerse por su domain correspondiente.

Ejemplo cURL de DomainConfig por Dominio

Copy

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

Estructura de Solicitud de DomainConfig por Dominio

Copy

interface DomainConfigsByDomainRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de DomainConfig por Dominio

Copy

interface DomainConfigResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'internal' | 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'missing-domain' | 'update-would-create-duplicate' | 'domain-does-not-exist'
    /** Included on failure. **/
    reason?: string
    configuration?: DomainConfig | null
}

POST /api/v1/domain-configs

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

Este endpoint de API proporciona la capacidad de crear configuraciones de dominio.

Agregar configuración para un dominio autoriza ese dominio para la cuenta de FastComments.

Los casos de uso comunes de esta API son la configuración inicial, si se desean agregar muchos dominios, o configuración personalizada para enviar emails.

Ejemplo cURL de POST de DomainConfig

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

Estructura de Solicitud de POST de DomainConfig

Copy

interface DomainConfigPostQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de POST de DomainConfig

Copy

interface DomainConfigPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'missing-domain' | 'configuration-exists-for-domain' | 'domain-too-long' | 'domain-invalid';
    /** Included on failure. **/
    reason?: string
    /** The created configuration. **/
    configuration?: DomainConfig
}

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

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

Este endpoint de API proporciona la capacidad de actualizar una configuración de dominio especificando solo el dominio y el atributo a actualizar.

Ejemplo cURL de PATCH de DomainConfig

Copy

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

Estructura de Solicitud de PATCH de DomainConfig

Copy

interface DomainConfigPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de PATCH de DomainConfig

Copy

interface DomainConfigPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'missing-domain' | 'domain-does-not-exist' | 'update-would-create-duplicate' | 'domain-too-long' | 'domain-invalid';
    /** Included on failure. **/
    reason?: string
    /** The updated configuration. **/
    configuration?: DomainConfig
}

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

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

Este endpoint de API proporciona la capacidad de reemplazar una configuración de dominio.

Ejemplo cURL de PUT de DomainConfig

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

Estructura de Solicitud de PUT de DomainConfig

Copy

interface DomainConfigPutQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de PUT de DomainConfig

Copy

interface DomainConfigPutResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'missing-domain' | 'domain-does-not-exist' | 'update-would-create-duplicate' | 'domain-too-long' | 'domain-invalid';
    /** Included on failure. **/
    reason?: string
    /** The updated configuration. **/
    configuration?: DomainConfig
}

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

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

Esta ruta proporciona la eliminación de un único DomainConfig por id.

Nota: Eliminar un DomainConfig desautorizará ese dominio de usar FastComments.
Nota: Re-agregar un dominio a través de la UI recreará el objeto (con solo domain poblado).

Ejemplo cURL de Eliminación de DomainConfig

Copy

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

Estructura de Solicitud de Eliminación de DomainConfig

Copy

interface DomainConfigRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Eliminación de DomainConfig

Copy

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

Estructura de configuración de pregunta

FastComments proporciona una forma de construir preguntas y agregar sus resultados. Un ejemplo de una pregunta (en adelante llamada QuestionConfig) podría ser una calificación de estrellas, un deslizador, o una pregunta NPS (determinado vía type).

Los datos de preguntas pueden agregarse individualmente, juntos, a lo largo del tiempo, en general, por página, y así sucesivamente.

El framework tiene todas las capacidades necesarias para construir widgets del lado del cliente (con su servidor frente a esta API), dashboards de administración, y herramientas de informes.

Primero, tenemos que definir un QuestionConfig. La estructura es la siguiente:

Estructura de QuestionConfig

Copy

type QuestionConfigType = 'nps' | 'slider' | 'star' | 'thumbs';
interface QuestionConfig {
    id: string
    tenantId: string
    name: string
    question: string
    helpText?: string
    createdAt: string
    createdBy: string
    /** READONLY - incremented for each new response. **/
    usedCount: number
    /** A date string for when the configuration was last used (result left). **/
    lastUsed?: string
    type: QuestionConfigType
    numStars?: number
    min?: number
    max?: number
    defaultValue?: number
    labelNegative?: string
    labelPositive?: string
    subQuestionIds?: string[]
    alwaysShowSubQuestions?: boolean
    reportingOrder: number
}

GET /api/v1/question-configs

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

Esta ruta devuelve hasta 100 objetos QuestionConfig a la vez, paginados. El costo es 1 por cada 100 objetos. Están ordenados por texto de pregunta ascendente (campo question).

Ejemplo de QuestionConfig

Copy

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

Estructura de Solicitud de QuestionConfig

Copy

interface QuestionConfigRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
    /** For pagination. Starts at 0. **/
    skip?: number
}

Estructura de Respuesta de QuestionConfig

Copy

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

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

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

Esta ruta devuelve un único QuestionConfig por su id.

Ejemplo cURL de QuestionConfig por ID

Copy

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

Estructura de Solicitud de QuestionConfig

Copy

interface QuestionConfigRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de QuestionConfig

Copy

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

POST /api/v1/question-configs

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

Este endpoint de API proporciona la capacidad de crear un QuestionConfig.

Ejemplo cURL de POST de QuestionConfig

Copy

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

Estructura de Solicitud de POST de QuestionConfig

Copy

interface QuestionConfigPostQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de POST de QuestionConfig

Copy

interface QuestionConfigPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input';
    /** Included on failure. **/
    reason?: string
    /** The created object. **/
    questionConfig?: QuestionConfig
}

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

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

Esta ruta proporciona la capacidad de actualizar un único QuestionConfig.

La siguiente estructura representa todos los valores que pueden cambiarse:

Estructura de QuestionConfig

Copy

interface QuestionConfigPatchBody {
    name?: string
    question?: string
    helpText?: string
    /** Beware! Changing type may throw off reporting if min/max is different. **/
    type?: QuestionConfigType
    numStars?: number
    min?: number
    max?: number
    defaultValue?: number
    labelNegative?: string
    labelPositive?: string
    subQuestionIds?: string[]
    alwaysShowSubQuestions?: boolean
    reportingOrder?: number
}

Ejemplo cURL de Actualización de QuestionConfig

Copy

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

Estructura de Solicitud de Actualización de QuestionConfig

Copy

interface QuestionConfigPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Actualización de QuestionConfig

Copy

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

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

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

Esta ruta proporciona la eliminación de un QuestionConfig por id.

Esto eliminará todos los resultados de preguntas correspondientes (pero no los comentarios). Esto es parte del alto costo de créditos.

Ejemplo cURL de Eliminación de QuestionConfig

Copy

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

Estructura de Solicitud de Eliminación de QuestionConfig

Copy

interface QuestionConfigDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Eliminación de QuestionConfig

Copy

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

Estructura de resultado de pregunta

Para guardar resultados de preguntas, crea un QuestionResult. Luego puede agregar resultados de preguntas, y también vincularlos a comentarios para propósitos de informes.

Estructura de 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

Esta ruta devuelve hasta 1000 objetos QuestionResults a la vez, paginados. El costo es 1 por cada 100 objetos. Están ordenados por createdAt, ascendente. Puede filtrar por varios parámetros.

Ejemplo de QuestionResults

Copy

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

Estructura de Solicitud de QuestionResults

Copy

interface QuestionResultsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** For pagination. Starts at 0. **/
    skip?: number
    /** For pagination. **/
    limit?: number
    /** Get the results from a specific page. **/
    urlId?: string
    /** Get the results from a specific user. **/
    userId?: string
    startDate?: string | number
    questionId?: string | string[]
}

Estructura de Respuesta de QuestionResults

Copy

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

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

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

Esta ruta devuelve un único QuestionResult por su id.

Ejemplo cURL de QuestionResult por ID

Copy

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

Estructura de Solicitud de QuestionResult

Copy

interface QuestionResultRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de QuestionResult

Copy

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

POST /api/v1/question-results

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

Este endpoint de API proporciona la capacidad de crear un QuestionResult.

Ejemplo cURL de POST de QuestionResult

Copy

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

Estructura de Solicitud de POST de QuestionResult

Copy

interface QuestionResultPostQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de POST de QuestionResult

Copy

interface QuestionResultPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input';
    /** Included on failure. **/
    reason?: string
    /** The created object. **/
    questionResult?: QuestionResult
}

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

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

Esta ruta proporciona la capacidad de actualizar un único QuestionResult.

La siguiente estructura representa todos los valores que pueden cambiarse:

Estructura de QuestionResult

Copy

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

Ejemplo cURL de Actualización de QuestionResult

Copy

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

Estructura de Solicitud de Actualización de QuestionResult

Copy

interface QuestionResultPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Actualización de QuestionResult

Copy

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

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

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

Esta ruta proporciona la eliminación de un QuestionResult por id.

Ejemplo cURL de Eliminación de QuestionResult

Copy

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

Estructura de Solicitud de Eliminación de QuestionResult

Copy

interface QuestionResultDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Estructura de Respuesta de Eliminación de QuestionResult

Copy

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

GET /api/v1/question-results-aggregate

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

Aquí es donde ocurre la agregación de resultados.

La estructura de respuesta de agregación es la siguiente:

Estructura de QuestionResultsAggregationResult

Copy

interface QuestionResultDataPoint {
    /** A map of value to count of occurrences of that value for the current data point (date bucket or page). **/
    v: Map<ValueAsString, number>
    total: number
}
interface QuestionResultsAggregationResult {
    /** Note - is null when timeBucket not specified. **/
    dataByDateBucket?: Map<DateString, QuestionResultDataPoint>
    dataByUrlId?: Map<URLIdString, QuestionResultDataPoint>
    countsByValue?: Map<ValueAsString, number>
    /** The total number of results aggregated. **/
    total: number
    /** The resulting weighted average. It is a float, usually two decimals or fewer. **/
    average: number
    /** A date string representing when this data was calculated, since it might come from cache. **/
    createdAt: string
}

Aquí están los parámetros de consulta disponibles para agregación:

Estructura de Solicitud de 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
}

Aquí hay una solicitud de ejemplo:

Ejemplo de 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'

Respuesta de ejemplo:

Ejemplo de Respuesta de 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
    }

Estructura de Respuesta de 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
}

Notas de Rendimiento

Para un fallo de caché las agregaciones generalmente toman cinco segundos por millón de resultados.
De lo contrario, las solicitudes son de tiempo constante.

Notas de Caché y Costo

Cuando se especifica forceRecalculate el costo es siempre 10, en lugar del normal 2.
Si el caché expira y los datos se recalculan, el costo sigue siendo un constante 2 si no se especifica forceRecalculate. El caché expira basándose en el tamaño del conjunto de datos agregado (puede variar entre 30 segundos y 5 minutos).
Esto es para incentivar el uso del caché.

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

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

Aquí es donde ocurre la combinación de resultados con comentarios. Útil para crear un gráfico de "comentarios positivos y negativos recientes" para un producto, por ejemplo.

Puede buscar vía un rango de valores (inclusivo), una o más preguntas, y por una fecha de inicio (inclusiva).

La estructura de respuesta es la siguiente:

Estructura de QuestionResultsCombinedWithCommentsResponse

Copy

interface SimpleComment {
    id: string
    commenterName: string
    userId?: string
    date: string
    commentHTML: string
}
interface SimpleQuestionResult {
    id: string
    value: number
}
interface CommentAndResult {
    comment: SimpleComment
    result: SimpleQuestionResult
}
interface QuestionResultsCombinedWithCommentsResponse {
    /** A date string representing when this data was calculated, since it might come from cache. **/
    createdAt: string
    results: CommentAndResult[]
}

Aquí están los parámetros de consulta disponibles para agregación:

Estructura de Solicitud de QuestionResultsCombineComments

Copy

interface QuestionResultsAggregateRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** You can aggregate results for one or more questions. **/
    questionId: string | string[]
    startDate?: string | number
    urlId?: string
    minValue: number
    maxValue: number
    limit?: number
    forceRecalculate?: boolean
}

Aquí hay una solicitud de ejemplo:

Ejemplo de 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'

Respuesta de ejemplo:

Ejemplo de Respuesta de 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
            }
        }
    ]
}

Estructura de Respuesta de QuestionResultsCombineComments

Copy

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

Notas de Caché y Costo

Cuando se especifica forceRecalculate el costo es siempre 10, en lugar del normal 2.
Si el caché expira y los datos se recalculan, el costo sigue siendo un constante 2 si no se especifica forceRecalculate.
Esto es para incentivar el uso del caché.

Estructura de insignia de usuario

UserBadge es un objeto que representa una insignia asignada a un usuario en el sistema FastComments.

Las insignias pueden ser asignadas a usuarios automáticamente basándose en su actividad (como cantidad de comentarios, tiempo de respuesta, estado de veterano) o manualmente por los administradores del sitio.

La estructura del objeto UserBadge es la siguiente:

Estructura de UserBadge

Copy

export interface UserBadge {
    /** Unique identifier for this user badge assignment */
    id: string
    /** ID of the user this badge is assigned to */
    userId: string
    /** ID of the badge definition from the tenant's badge catalog */
    badgeId: string
    /** ID of the tenant that created/assigned this badge */
    fromTenantId: string
    /** When this badge was created (milliseconds since epoch) */
    createdAt?: number
    /** When this badge was received by the user (milliseconds since epoch) */
    receivedAt?: number
    /**
     * The badge type:
     * 0=CommentCount, 1=CommentUpVotes, 2=CommentReplies, 3=CommentsPinned,
     * 4=Veteran, 5=NightOwl, 6=FastReplyTime, 7=ModeratorCommentsDeleted,
     * 8=ModeratorCommentsApproved, 9=ModeratorCommentsUnapproved, 10=ModeratorCommentsReviewed,
     * 11=ModeratorCommentsMarkedSpam, 12=ModeratorCommentsMarkedNotSpam, 13=RepliedToSpecificPage,
     * 14=Manual
     */
    type: number
    /** For threshold-based badges, the threshold value */
    threshold?: number
    /** The name/label of the badge */
    name?: string
    /** Detailed description of the badge */
    description?: string
    /** The text shown on the badge */
    displayLabel?: string
    /** URL to an image shown on the badge */
    displaySrc?: string
    /** Background color for the badge (hex code) */
    backgroundColor?: string
    /** Border color for the badge (hex code) */
    borderColor?: string
    /** Text color for the badge (hex code) */
    textColor?: string
    /** Additional CSS class for styling */
    cssClass?: string
    /** For veteran badges, the time threshold in milliseconds */
    veteranUserThresholdMillis?: number
    /** Whether this badge is displayed on the user's comments */
    displayedOnComments: boolean
    /** The display order of the badge */
    order?: number
}

GET /api/v1/user-badges

Este endpoint le permite obtener insignias de usuario basadas en varios criterios.

Ejemplo de Solicitud:

Ejemplo de Solicitud GET

Copy

Run

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

Puede agregar varios parámetros de consulta para filtrar los resultados:

userId - Obtener insignias para un usuario específico
badgeId - Obtener instancias de una insignia específica
type - Filtrar por tipo de insignia (0=CommentCount, 1=CommentUpVotes, 2=CommentReplies, etc. Ver estructura de UserBadge para la lista completa)
displayedOnComments - Filtrar por si la insignia se muestra en comentarios (true/false)
limit - Número máximo de insignias a devolver (predeterminado 30, máximo 200)
skip - Número de insignias a omitir (para paginación)

Ejemplo de Respuesta:

Respuesta

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

Posibles Respuestas de Error:

Error: Falta ID de Inquilino

Copy

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

Error: Límite Inválido

Copy

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

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

Este endpoint le permite obtener una insignia de usuario específica por su ID único.

Ejemplo de Solicitud:

Ejemplo de Solicitud GET

Copy

Run

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

Ejemplo de Respuesta:

Respuesta

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

Posibles Respuestas de Error:

Error: Falta ID de Inquilino

Copy

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

Error: No Encontrado

Copy

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

POST /api/v1/user-badges

Este endpoint le permite crear una nueva asignación de insignia de usuario.

Ejemplo de Solicitud:

Ejemplo de Solicitud 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
}'

El cuerpo de la solicitud debe contener los siguientes parámetros:

userId (requerido) - El ID del usuario al que se asignará la insignia
badgeId (requerido) - El ID de la insignia a asignar
displayedOnComments (opcional) - Si la insignia debe mostrarse en los comentarios del usuario (por defecto es true)

Notas Importantes:

La insignia debe existir y estar habilitada en el catálogo de insignias de su inquilino
Solo puede asignar insignias a usuarios que pertenecen a su inquilino o han comentado en su sitio

Ejemplo de Respuesta:

Respuesta

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

Posibles Respuestas de Error:

Error: Falta ID de Inquilino

Copy

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

Error: Falta ID de Usuario

Copy

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

Error: Falta ID de Insignia

Copy

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

Error: Insignia No Encontrada

Copy

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

Error: Usuario No Autorizado

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

Este endpoint le permite actualizar una asignación de insignia de usuario.

Actualmente, la única propiedad que puede actualizarse es displayedOnComments, que controla si la insignia se muestra en los comentarios del usuario.

Ejemplo de Solicitud:

Ejemplo de Solicitud 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
}'

Ejemplo de Respuesta:

Respuesta

Copy

{
  "status": "success"
}

Posibles Respuestas de Error:

Error: Falta ID de Inquilino

Copy

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

Error: Falta ID

Copy

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

Error: No Encontrado

Copy

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

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

Este endpoint le permite eliminar una asignación de insignia de usuario.

Ejemplo de Solicitud:

Ejemplo de Solicitud DELETE

Copy

Run

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

Ejemplo de Respuesta:

Respuesta

Copy

{
  "status": "success"
}

Posibles Respuestas de Error:

Error: Falta ID de Inquilino

Copy

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

Error: Falta ID

Copy

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

Error: No Encontrado

Copy

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

Estructura de progreso de insignia de usuario

UserBadgeProgress es un objeto que representa el progreso de un usuario hacia la obtención de varias insignias en el sistema FastComments.

Este seguimiento ayuda a determinar cuándo los usuarios deben recibir insignias automáticas basadas en su actividad y participación en su comunidad.

La estructura del objeto UserBadgeProgress es la siguiente:

Estructura de UserBadgeProgress

Copy

export interface UserBadgeProgress {
    /** Unique identifier for this progress record */
    id: string
    /** ID of the tenant this progress record belongs to */
    tenantId: string
    /** ID of the user this progress record tracks */
    userId: string
    /** ID of the user's first comment in the system */
    firstCommentId?: string
    /** Date of the user's first comment (milliseconds since epoch) */
    firstCommentDate?: number
    /** Automatically calculated trust factor based on user activity */
    autoTrustFactor?: number
    /** Manually set trust factor by administrators */
    manualTrustFactor?: number
    /** Detailed progress object with various metrics, keys match BadgeType enum */
    progress: {
        /** 0: CommentCount - Count of comments the user has made */
        '0'?: number
        /** 1: CommentUpVotes - Count of upvotes the user has received */
        '1'?: number
        /** 2: CommentReplies - Count of replies the user has made */
        '2'?: number
        /** 3: CommentsPinned - Count of pinned comments the user has */
        '3'?: number
        /** 4: Veteran - User's account age */
        '4'?: number
        /** 5: NightOwl - Times user has posted during nighttime hours */
        '5'?: number
        /** 6: FastReplyTime - Average reply time in milliseconds */
        '6'?: number
        /** 7: ModeratorCommentsDeleted - For moderator badges, comments deleted count */
        '7'?: number
        /** 8: ModeratorCommentsApproved - For moderator badges, comments approved count */
        '8'?: number
        /** 9: ModeratorCommentsUnapproved - For moderator badges, comments unapproved count */
        '9'?: number
        /** 10: ModeratorCommentsReviewed - For moderator badges, comments reviewed count */
        '10'?: number
        /** 11: ModeratorCommentsMarkedSpam - For moderator badges, comments marked as spam count */
        '11'?: number
        /** 12: ModeratorCommentsMarkedNotSpam - For moderator badges, comments marked as not spam count */
        '12'?: number
        /** 13: RepliedToSpecificPage - For each page, count of replies */
        '13'?: Record<string, number>
    }
}

GET /api/v1/user-badge-progress

Este endpoint le permite obtener registros de progreso de insignias de usuario basados en varios criterios.

Ejemplo de Solicitud:

Ejemplo de Solicitud GET

Copy

Run

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

Puede agregar varios parámetros de consulta para filtrar los resultados:

userId - Obtener progreso para un usuario específico
limit - Número máximo de registros a devolver (predeterminado 30, máximo 200)
skip - Número de registros a omitir (para paginación)

Ejemplo de Respuesta:

Respuesta

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

Posibles Respuestas de Error:

Error: Falta ID de Inquilino

Copy

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

Error: Límite Inválido

Copy

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

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

Este endpoint le permite obtener un registro específico de progreso de insignia de usuario por su ID único.

Ejemplo de Solicitud:

Ejemplo de Solicitud GET

Copy

Run

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

Ejemplo de Respuesta:

Respuesta

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

Posibles Respuestas de Error:

Error: Falta ID de Inquilino

Copy

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

Error: No Encontrado

Copy

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

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

Este endpoint le permite obtener el registro de progreso de insignias de un usuario por su ID de usuario.

Ejemplo de Solicitud:

Ejemplo de Solicitud GET

Copy

Run

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

Ejemplo de Respuesta:

Respuesta

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

Posibles Respuestas de Error:

Error: Falta ID de Inquilino

Copy

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

Error: Falta ID de Usuario

Copy

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

Error: No Encontrado

Copy

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

En conclusión

Esperamos que haya encontrado nuestra documentación de la API detallada y fácil de entender. Si encuentra alguna laguna, háganoslo saber abajo.

Idioma 🇪🇸 Español

Recursos de la API

Agregaciones

Registros de auditoría

Comentarios

Plantillas de correo electrónico

Hashtags

Moderadores

Conteo de notificaciones

Notificaciones

Páginas

Eventos de webhook pendientes

Usuarios SSO

Suscripciones

Uso diario del tenant

Tenants

Paquetes de tenant

Usuarios del tenant

Usuarios

Votos

Configuraciones de dominio

Configuraciones de preguntas

Resultados de preguntas

Agregación de resultados de preguntas

Insignias de usuario

Progreso de insignia de usuario

La API de FastComments

SDKs Generados

Autenticación

Nota de seguridad

Opción de autenticación uno - Encabezados

Opción de autenticación dos - Parámetros de consulta

Recursos de la API

Uso de Recursos

¡Nota!

Agregue sus datos

Ejemplos

Ejemplo: Contar Únicos

Ejemplo: Contar Distintos

Ejemplo: Sumar Valores de Múltiples Campos

Ejemplo: Promediar Valores de Múltiples Campos

Ejemplo: Valores Mín/Máx de Múltiples Campos

Ejemplo: Contar Valores Únicos de Múltiples Campos

Ejemplo: Creación de Consulta

Ejemplo: Contar Comentarios Pendientes de Revisión

Ejemplo: Desglose de Comentarios Aprobados, Revisados y Spam

Estructuras

Estructura de registro de auditoría

GET /api/v1/audit-logs

Estructura de comentario

Estructura del Texto del Comentario

Etiquetado

HashTags

GET /api/v1/comments

Paginación

Hilos

Árboles Explicados

Obtener Comentarios en el Contexto de un Usuario

Obtener Comentarios como Árbol

Obtener Comentarios como Árbol, Buscando por Hash Tag

Todos los Parámetros de Solicitud

La Respuesta

Consejos Útiles

URL ID

Acciones Anónimas

Comentarios No Devueltos

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

Estructura de plantilla de correo electrónico

Notas

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

GET /api/v1/email-templates

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

POST /api/v1/email-templates