APIs de Comentários ao Vivo

Uso de Recursos

Deve‑se observar que a obtenção de dados da API é contabilizada como uso em sua conta.

Cada recurso listará qual é esse uso em sua própria seção.

Alguns recursos custam mais para servir do que outros. Cada endpoint tem um custo fixo de créditos por chamada de API. Para alguns endpoints, o número de créditos varia com base nas opções e nos tamanhos das respostas.

O uso da API pode ser verificado na página Análise de Faturamento e é atualizado a cada poucos minutos.

Nota!

Recomendamos ler a documentação de Pages primeiro, para ajudar a limitar a confusão ao determinar quais valores passar para urlId na API de Comentários.

Webhooks

As assinaturas de Webhook têm seu próprio guia. POST, GET e DELETE /api/v1/webhooks, e GET /api/v1/webhooks/sample-payloads, estão documentados em Gerenciando Assinaturas via API, e as cargas úteis de eventos em Estruturas de Webhook.

O FastComments é um servidor de autorização OAuth 2.1. Um aplicativo pode obter um token vinculado a uma conta do FastComments e usá-lo em todos os endpoints deste guia no lugar de uma chave de API. É assim que o aplicativo Zapier, o servidor MCP e outras integrações de terceiros se conectam.

Os tokens são emitidos por meio do fluxo de código de autorização com PKCE. Não há client credentials nem grant implícito.

Discovery

As localizações dos endpoints, os grants suportados e os métodos de autenticação são publicados na URL de metadados padrão:

Metadados do Servidor de Autorização

Copy

1

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

3

Os endpoints que ele descreve:

Endpoints OAuth

Copy

1

2GET https://fastcomments.com/oauth/authorize

3POST https://fastcomments.com/oauth/token

4POST https://fastcomments.com/oauth/revoke

5POST https://fastcomments.com/oauth/register

6

Contas na região da UE usam https://eu.fastcomments.com como issuer, com os mesmos caminhos.

Registrando um cliente

Um cliente precisa de um client_id e de um redirect_uri registrado antes de poder iniciar o fluxo. Há duas maneiras de obter um:

• Registro Dinâmico de Cliente. POST /oauth/register com um corpo JSON conforme a RFC 7591 (redirect_uris, client_name, client_uri, logo_uri, token_endpoint_auth_method). A resposta contém o client_id e, para clientes confidenciais, o client_secret. O registro não é autenticado e tem limite de taxa por IP.
• Documento de Metadados de Client ID. O cliente usa uma URL https que ele controla como seu client_id. O FastComments busca essa URL e lê os mesmos campos de metadados dela. Nenhuma chamada de registro é necessária.

Aplicativos parceiros listados no painel do FastComments, como o Zapier, são registrados pelo FastComments diretamente. Entre em contato com o suporte se você estiver criando um anúncio de marketplace e precisar de um cliente de primeira parte.

Scopes

Scopes

Copy

1

2read GET and HEAD requests

3write every other method

4

Uma solicitação que não pede nenhum scope recebe ambos. O usuário vê os scopes solicitados na página de consentimento. Uma solicitação de um scope diferente desses dois falha com invalid_scope.

Etapa 1 - Solicitação de autorização

Envie o navegador do usuário para o endpoint de autorização. PKCE com o método S256 é obrigatório para todos os clientes.

Solicitação de Autorização

Copy

1

2GET https://fastcomments.com/oauth/authorize

3 ?response_type=code

4 &client_id=YOUR_CLIENT_ID

5 &redirect_uri=https://example.com/oauth/callback

6 &scope=read%20write

7 &state=RANDOM_STATE

8 &code_challenge=BASE64URL_SHA256_OF_VERIFIER

9 &code_challenge_method=S256

10

Parâmetros da Solicitação de Autorização

Copy

1

2interface OAuthAuthorizeQueryParams {

3 response_type: 'code'

4 client_id: string

5 /** Must exactly match one of the client's registered redirect URIs. **/

6 redirect_uri: string

7 /** Space separated. Omit to request both scopes. **/

8 scope?: 'read' | 'write' | 'read write'

9 /** Returned unchanged on the redirect. Use it to bind the callback to the session that started the flow. **/

10 state?: string

11 /** base64url(sha256(code_verifier)). **/

12 code_challenge: string

13 code_challenge_method: 'S256'

14 /** Optional RFC 8707 resource indicator. If sent, the same value must be sent to the token endpoint. **/

15 resource?: string

16}

17

O usuário faz login no FastComments, se necessário, e vê uma página de consentimento que nomeia seu aplicativo, a conta à qual ele será conectado e os scopes solicitados. O usuário deve ter a permissão API Admin nessa conta; qualquer outra pessoa vê um erro de permissão em vez do formulário de consentimento. Aprovar redireciona o navegador para o seu redirect_uri com code e state. Recusar redireciona com error=access_denied.

O código de autorização é válido por 10 minutos e pode ser trocado uma vez. Uma segunda troca do mesmo código revoga todos os tokens produzidos pela primeira troca.

Etapa 2 - Solicitação de token

Troque o código por tokens. O corpo é codificado como form. Clientes confidenciais se autenticam com client_secret_basic (HTTP Basic) ou client_secret_post (segredo no corpo). Clientes públicos enviam apenas client_id.

Exemplo de Solicitação de Token com cURL

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/oauth/token' \

4 --header 'Content-Type: application/x-www-form-urlencoded' \

5 --data 'grant_type=authorization_code' \

6 --data 'client_id=YOUR_CLIENT_ID' \

7 --data 'client_secret=YOUR_CLIENT_SECRET' \

8 --data 'code=fcac_...' \

9 --data 'code_verifier=YOUR_PKCE_VERIFIER' \

10 --data 'redirect_uri=https://example.com/oauth/callback'

11

Corpo da Solicitação de Token (authorization_code)

Copy

1

2interface OAuthTokenRequestAuthorizationCode {

3 grant_type: 'authorization_code'

4 client_id: string

5 /** Confidential clients only. May be sent as HTTP Basic auth instead. **/

6 client_secret?: string

7 code: string

8 code_verifier: string

9 /** Must match the authorization request when sent. **/

10 redirect_uri?: string

11 resource?: string

12}

13

Estrutura da Resposta de Token

Copy

1

2interface OAuthTokenResponse {

3 /** Prefixed fcat_. Valid for one hour. **/

4 access_token: string

5 token_type: 'bearer'

6 /** Seconds until the access token expires. 3600. **/

7 expires_in: number

8 /** Prefixed fcrt_. Valid for 30 days from issue. **/

9 refresh_token: string

10 /** Space separated scopes granted. **/

11 scope: string

12}

13

Os erros seguem a RFC 6749: um corpo JSON com error e error_description, HTTP 400 para invalid_request, invalid_grant, invalid_scope, invalid_target e unsupported_grant_type, HTTP 401 para invalid_client, HTTP 429 quando há limite de taxa.

Etapa 3 - Chamando a API

Envie o access token como um bearer token. O tenant é implícito pelo token, então tenantId é opcional. Quando fornecido, deve corresponder ao token ou a solicitação falha.

Exemplo de Bearer Token com cURL

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/me' \

4 --header 'Authorization: Bearer fcat_...'

5

GET /api/v1/me retorna o tenant, o usuário autorizante e os scopes concedidos, o que o torna a chamada certa para um teste de conexão. Uma solicitação com um token expirado ou revogado recebe HTTP 401. Uma solicitação cujo método precisa de um scope que o token não possui recebe HTTP 403.

Etapa 4 - Atualizando

Exemplo de Solicitação de Refresh com cURL

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/oauth/token' \

4 --header 'Content-Type: application/x-www-form-urlencoded' \

5 --data 'grant_type=refresh_token' \

6 --data 'client_id=YOUR_CLIENT_ID' \

7 --data 'client_secret=YOUR_CLIENT_SECRET' \

8 --data 'refresh_token=fcrt_...'

9

Corpo da Solicitação de Token (refresh_token)

Copy

1

2interface OAuthTokenRequestRefreshToken {

3 grant_type: 'refresh_token'

4 client_id: string

5 client_secret?: string

6 refresh_token: string

7 /** Optional. Narrows to a subset of the scopes originally granted. **/

8 scope?: string

9 resource?: string

10}

11

A resposta tem a mesma forma da troca de código. Os refresh tokens rotacionam: cada refresh retorna um novo refresh_token e revoga o antigo após uma janela de carência de 30 segundos para solicitações concorrentes. Apresentar um refresh token que foi rotacionado há mais de 30 segundos é tratado como replay e revoga todo o grant. Aplicativos parceiros registrados pelo FastComments são isentos da rotação e recebem de volta o mesmo refresh token com sua validade estendida por mais 30 dias.

Um refresh também verifica novamente se o usuário autorizante ainda possui API Admin na conta. Caso contrário, o grant é revogado e a resposta é invalid_grant.

Revogação

Exemplo de Solicitação de Revogação com cURL

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/oauth/revoke' \

4 --header 'Content-Type: application/x-www-form-urlencoded' \

5 --data 'client_id=YOUR_CLIENT_ID' \

6 --data 'client_secret=YOUR_CLIENT_SECRET' \

7 --data 'token=fcrt_...' \

8 --data 'token_type_hint=refresh_token'

9

Revogar um refresh token revoga todos os access tokens emitidos a partir do mesmo grant. Revogar um access token revoga apenas esse token. O endpoint retorna HTTP 200 com um objeto JSON vazio, independentemente de o token ter sido encontrado ou não, conforme a RFC 7009.

Os usuários também podem revogar uma conexão em Connected Apps no painel do FastComments. Todos os tokens desse aplicativo param de funcionar imediatamente.

Esta API agrega documentos agrupando-os (se groupBy for fornecido) e aplicando múltiplas operações. Diferentes operações (por exemplo sum, countDistinct, avg, etc.) são suportadas.

O custo é variável. A cada 500 objetos analisados custa 1 crédito de API.

O uso máximo de memória permitido por chamada de API por padrão é 64MB, e por padrão você pode ter apenas uma agregação em execução por vez. Se você enviar múltiplas agregações simultaneamente, elas serão enfileiradas e executadas na ordem em que foram submetidas. Agregações pendentes aguardarão no máximo 60 segundos, após isso a solicitação expirará. Agregações individuais podem executar por até 5 minutos.

Se você tem tenants gerenciados, pode agregar todos os recursos de tenants filhos em uma única chamada passando o parâmetro de query parentTenantId.

Exemplos

Exemplo: Contar valores únicos

Exemplo cURL: Contar valores únicos

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "distinct", "field": "urlId", "alias": "urlId" },

6 { "op": "distinct", "field": "commenterEmail", "alias": "commenterEmail" }

7 ]

8}'

9

Resposta: Contagem de valores únicos

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "commenterEmail": {

7 "distinctCounts": {

8 "someone@somewhere.com": 1,

9 "someone2@somewhere.com": 1

10 }

11 }

12 },

13 {

14 "urlId": {

15 "distinctCounts": {

16 "some-page": 2

17 }

18 }

19 }

20 ],

21 "stats": { "scanned": 2 }

22}

23

Exemplo: Contar distintos

Exemplo cURL: Contar valores distintos

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "countDistinct", "field": "urlId", "alias": "urlId" },

6 { "op": "countDistinct", "field": "commenterEmail", "alias": "commenterEmail" }

7 ]

8}'

9

Resposta:

Resposta: Contagem de valores distintos

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "commenterEmail": { "distinctCount": 2 },

7 "urlId": { "distinctCount": 1 }

8 }

9 ],

10 "stats": { "scanned": 2 }

11}

12

Exemplo: Somar valores de múltiplos campos

Exemplo cURL: Soma de valores

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "sum", "field": "votes", "alias": "votes" },

6 { "op": "sum", "field": "votesUp", "alias": "votesUp" }

7 ]

8}'

9

Resposta:

Resposta: Soma de valores

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "votes": { "numericValue": 2 },

7 "votesUp": { "numericValue": 2 }

8 }

9 ],

10 "stats": { "scanned": 2 }

11}

12

Exemplo: Média dos valores de múltiplos campos

Exemplo cURL: Média de valores

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "avg", "field": "votes", "alias": "votes" },

6 { "op": "avg", "field": "votesUp", "alias": "votesUp" }

7 ]

8}'

9

Resposta:

Resposta: Média de valores

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "votes": { "numericValue": 1 },

7 "votesUp": { "numericValue": 1 }

8 }

9 ],

10 "stats": { "scanned": 2 }

11}

12

Exemplo: Valores mínimos/máximos de múltiplos campos

Exemplo cURL: Valores mínimos/máximos

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "min", "field": "votes", "alias": "votes" },

6 { "op": "min", "field": "votesUp", "alias": "votesUp" },

7 { "op": "max", "field": "votes", "alias": "votes" },

8 { "op": "max", "field": "votesUp", "alias": "votesUp" }

9 ]

10}'

11

Resposta:

Resposta: Valores mínimos/máximos

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "votes": { "numericValue": 0 },

7 "votesUp": { "numericValue": 0 },

8 "votes": { "numericValue": 2 },

9 "votesUp": { "numericValue": 2 }

10 }

11 ],

12 "stats": { "scanned": 2 }

13}

14

Exemplo: Contar valores únicos de múltiplos campos

Exemplo cURL: Contar valores únicos

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "distinct", "field": "urlId", "alias": "urlId" },

6 { "op": "distinct", "field": "commenterEmail", "alias": "commenterEmail" }

7 ]

8}'

9

Resposta:

Resposta: Contagem de valores únicos

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "commenterEmail": {

7 "distinctCounts": {

8 "someone@somewhere.com": 1,

9 "someone2@somewhere.com": 1

10 }

11 },

12 "urlId": {

13 "distinctCounts": {

14 "some-page": 2

15 }

16 }

17 }

18 ],

19 "stats": { "scanned": 2 }

20}

21

Exemplo: Criação de consulta

Exemplo cURL: Criação de consulta

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "groupBy": ["commenterName"],

5 "query": [

6 { "key": "approved", "value": true, "operator": "eq" },

7 { "key": "commenterName", "value": "some-username-2", "operator": "eq" }

8 ],

9 "operations": [

10 { "op": "sum", "field": "votes", "alias": "votes" }

11 ]

12}'

13

Resposta:

Resposta: Criação de consulta

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "groups": { "commenterName": "some-username-2" },

7 "votes": { "numericValue": 2 }

8 }

9 ],

10 "stats": { "scanned": 1 }

11}

12

Exemplo: Contar comentários pendentes de revisão

Exemplo cURL: Contar comentários pendentes de revisão

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "query": [

5 { "key": "reviewed", "value": true, "operator": "not_eq" }

6 ],

7 "operations": [

8 { "op": "count", "field": "id", "alias": "count" }

9 ]

10}'

11

Resposta:

Resposta: Contagem de comentários pendentes de revisão

Copy

1

2{

3 "status": "success",

4 "data": [

5 { "count": { "numericValue": 2 } }

6 ],

7 "stats": { "scanned": 2 }

8}

9

Exemplo: Distribuição de comentários aprovados, revisados e spam

Exemplo cURL: Distribuição dos comentários

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "distinct", "field": "approved", "alias": "approved" },

6 { "op": "distinct", "field": "reviewed", "alias": "reviewed" },

7 { "op": "distinct", "field": "isSpam", "alias": "isSpam" }

8 ]

9}'

10

Resposta:

Resposta: Distribuição dos comentários

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "approved": { "distinctCounts": { "true": 2 } },

7 "reviewed": { "distinctCounts": { "false": 2 } },

8 "isSpam": { "distinctCounts": { "false": 2 } }

9 }

10 ],

11 "stats": { "scanned": 2 }

12}

13

Estruturas

Estrutura da Requisição Aggregate

Copy

1

2export type AggregationOpType = 'sum' | 'countDistinct' | 'distinct' | 'avg' | 'min' | 'max' | 'count';

3

4/** Uma operação que será aplicada a um campo */

5export interface AggregationOperation {

6 /** O campo sobre o qual operar */

7 field: string;

8 /** O tipo de operação */

9 op: AggregationOpType;

10 /** Alias opcional para a saída; se não fornecido, um alias padrão é calculado */

11 alias?: string;

12 expandArray?: boolean;

13}

14

15export interface QueryPredicate {

16 key: string

17 value: string | number | boolean

18 operator: 'eq' | 'not_eq' | 'greater_than' | 'less_than' | 'contains'

19}

20

21export interface AggregationRequest {

22 query?: QueryPredicate[];

23 resourceName: string;

24 groupBy?: string[];

25 operations: AggregationOperation[];

26 sort?: {

27 field: string;

28 dir: 'asc' | 'desc';

29 };

30}

31

32type DistinctAccumulator = Record<string, number>;

33type GroupValues = Record<string, string>;

34

35export type AggregationValue = {

36 distinctCounts?: DistinctAccumulator

37 distinctCount?: number

38 numericValue?: number

39 stringValue?: string

40 groups?: GroupValues

41};

42

Estrutura da Resposta Aggregate

Copy

1

2export type AggregationItem = Record<string, AggregationValue> & { groups?: GroupValues };

3

4export interface AggregationResponse {

5 status: APIStatus,

6 data: AggregationItem[];

7 stats?: {

8 scanned: number;

9 timeMS: number;

10 };

11}

12

Os seguintes recursos podem 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

Esta API usa paginação, fornecida pelos parâmetros skip, limit, before e after. AuditLogs são retornados em páginas de 1000 por padrão, até um limit máximo de 10000, ordenados por when e id. As páginas são grandes porque este endpoint geralmente é usado para exportar o histórico em vez de paginar interativamente.

Cada 100 logs retornados tem um custo de crédito de 1.

Por padrão, você receberá uma lista com os itens mais recentes primeiro. Dessa forma, você pode fazer polling começando com skip=0, paginando até encontrar o último registro que consumiu.

Alternativamente, você pode ordenar do mais antigo para o mais recente e paginar até que não haja mais registros.

A ordenação pode ser feita definindo order como ASC ou DESC. O padrão é DESC.

Consultar por data é possível via before e after como timestamps em milissegundos. before e after NÃO são inclusivos, e cada um pode ser usado isoladamente.

Encontrando o que aconteceu com uma pessoa

Cada evento registra quem o realizou (username, userId, ip) e, separadamente, sobre o que ele foi realizado. targetLabel é um rótulo legível para aquele objeto, por exemplo jsmith (jsmith@example.com), e targetId é seu id. Use target para uma correspondência de substring sem distinção entre maiúsculas e minúsculas no rótulo quando você conhece o nome ou e‑mail de uma pessoa, mas não seu id.

Exclusões capturam o rótulo no momento do evento, de modo que um usuário ou moderador removido ainda pode ser identificado após o registro subjacente ser excluído.

Inquilinos gerenciados

Se o seu inquilino gerencia outros inquilinos, defina includeManagedTenants=true para retornar eventos do seu inquilino e de todos os inquilinos que ele gerencia em uma única resposta. O tenantId de cada log retornado indica de qual inquilino ele provém.

Exemplo cURL de AuditLog

Copy

1

2curl --request GET \

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

4

Estrutura de Requisição AuditLog

Copy

1

2interface AuditLogsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 order?: 'ASC' | 'DESC'

6 /** Max 10000. Defaults to 1000. **/

7 limit?: number

8 skip?: number

9 before?: number

10 after?: number

11 /** Only events performed by this username. **/

12 username?: string

13 /** Only events from this IP address. **/

14 ip?: string

15 /** Only events of this type. **/

16 crudType?: 'c' | 'r' | 'u' | 'd' | 'login'

17 /** Only events for this resource, e.g. User or Moderator. **/

18 resourceName?: string

19 /** Only events whose affected object has this id. **/

20 targetId?: string

21 /** Case-insensitive substring match on the affected object's label. **/

22 target?: string

23 /** Also return events from tenants this tenant manages. **/

24 includeManagedTenants?: boolean

25}

26

Estrutura de Resposta AuditLog

Copy

1

2interface AuditLogsResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'invalid-limit' | 'invalid-skip'

6 /** Included on failure. **/

7 reason?: string

8 /** The logs! **/

9 auditLogs: AuditLog[]

10}

11

Esta rota retorna os jobs em lote do locatário de todos os tipos, mais recentes primeiro, 100 por página. Use type e status para filtrar a lista e skip para paginar.

Exemplo cURL da Lista de BatchJob

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/batch-jobs?tenantId=demo&API_KEY=DEMO_API_SECRET&type=migrate-pages&status=running'

4

Estrutura da Solicitação da Lista de BatchJob

Copy

1

2interface BatchJobsQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Somente jobs deste tipo, por exemplo migrate-pages. **/

6 type?: string

7 status?: 'requested' | 'running' | 'success' | 'failed'

8 /** Quantos jobs pular, para paginação. Um inteiro não negativo. **/

9 skip?: number

10}

11

Estrutura da Resposta da Lista de BatchJob

Copy

1

2interface BatchJobsResponse {

3 status: 'success' | 'failed'

4 /** Incluído em caso de falha. **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'invalid-skip' | 'internal'

6 /** Incluído em caso de falha. **/

7 reason?: string

8 /** Mais recentes primeiro, no máximo 100. **/

9 batchJobs?: BatchJob[]

10}

11

Esta rota retorna o status, o progresso e, uma vez concluído, o resultado de um job em lote. Use-a para acompanhar um job iniciado por POST /api/v1/pages/migrations ou POST /api/v1/pages/migrations/:undoId/undo.

Um job é concluído quando seu status é success ou failed. Cada chamada custa 1 crédito, portanto faça polling a cada poucos segundos em vez de continuamente.

Exemplo cURL de BatchJob por ID

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/batch-jobs/my-batch-job-id?tenantId=demo&API_KEY=DEMO_API_SECRET'

4

Estrutura de Requisição de BatchJob por ID

Copy

1

2interface BatchJobQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Estrutura de Resposta de BatchJob por ID

Copy

1

2interface BatchJobResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'internal'

6 /** Included on failure. **/

7 reason?: string

8 batchJob?: BatchJob

9}

10

Exemplo de Job de Migração de Página Concluído

Copy

1

2{

3 "status": "success",

4 "batchJob": {

5 "id": "my-batch-job-id",

6 "type": "migrate-pages",

7 "status": "success",

8 "createdAt": "2026-10-19T16:00:00.000Z",

9 "completedAt": "2026-10-19T16:00:12.000Z",

10 "processedCount": 2,

11 "totalCount": 2,

12 "pageMigrationResults": [

13 {"from": "old-post-id", "to": "new-post-id", "type": "urlId", "status": "success", "commentsMigrated": 42},

14 {"from": "old.example.com", "to": "new.example.com", "type": "domain", "status": "success", "commentsMigrated": 1250}

15 ],

16 "undoId": "my-undo-id"

17 }

18}

19

Esta API é usada para obter comentários para exibição ao usuário. Por exemplo, ela filtra automaticamente comentários não aprovados ou de spam.

Paginação

Paginação pode ser feita de duas maneiras, dependendo dos requisitos de desempenho e caso de uso:

1. **Mais rápido: Paginação Precalculada:
   1. É assim que o FastComments funciona quando você usa nossos widgets e clientes pré-construídos.
   2. Clicar em "next" simplesmente aumenta a contagem de páginas.
   3. Você pode pensar nisso como sendo recuperado por um armazenamento chave-valor.
   4. Dessa forma, basta definir um parâmetro page começando em 0 e uma direção de ordenação como direction.
   5. Os tamanhos de página podem ser personalizados via regras de customização.
2. **Mais flexível: Paginação Flexível:
   1. Dessa forma, você pode definir parâmetros personalizados limit e skip. Não passe page.
   2. direction de ordenação também é suportado.
   3. limit é o número total a ser retornado após a aplicação de skip.
      • Exemplo: defina skip = 200, limit = 100 quando page size = 100 e page = 2.
   4. Comentários filhos ainda contam na paginação. Você pode contornar isso usando a opção asTree.
      • Você pode paginar filhos via limitChildren e skipChildren.
      • Você pode limitar a profundidade dos tópicos retornados via maxTreeDepth.

Tópicos

1. Ao usar Paginação Precalculada, os comentários são agrupados por página e os comentários nos tópicos afetam a página geral.
   1. Dessa forma, os tópicos podem ser determinados no cliente com base em parentId.
   2. Por exemplo, com uma página contendo um comentário de nível superior e 29 respostas, e definindo page=0 na API – você receberá apenas o comentário de nível superior e os 29 filhos.
2. Ao usar Paginação Flexível, você pode definir um parâmetro parentId.
   1. Defina isso como null para obter apenas comentários de nível superior.
   2. Então, para visualizar os tópicos, chame a API novamente e passe parentId.
   3. Uma solução comum é fazer uma chamada de API para os comentários de nível superior e então fazer chamadas paralelas de API para obter os comentários dos filhos de cada comentário.
3. NOVO A partir de fev de 2023! Busque como árvore usando &asTree=true.
   1. Você pode pensar nisso como Paginação Flexível como Árvore.
   2. Apenas os comentários de nível superior contam na paginação.
   3. Defina parentId=null para iniciar a árvore na raiz (você deve definir parentId).
   4. Defina skip e limit para paginação.
   5. Defina asTree como true.
   6. O custo de créditos aumenta em 2x, pois nosso backend precisa fazer muito mais trabalho neste cenário.
   7. Defina maxTreeDepth, limitChildren e skipChildren conforme desejado.

Árvores Explicadas

Ao usar asTree, pode ser difícil raciocinar sobre paginação. Aqui está um gráfico útil:

Diagrama de Paginação de Árvore

Obtendo Comentários no Contexto de um Usuário

A API /comments pode ser usada em dois contextos, para diferentes casos de uso:

• Para retornar comentários ordenados e marcados com informações para construir seu próprio cliente.
  • Neste caso, defina um parâmetro de consulta contextUserId.
• Para buscar comentários do seu backend para integrações personalizadas.
  • A plataforma usará isso por padrão sem contextUserId.

Comentários Paginação Precalculada

Copy

1

2curl --request GET \

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

4

Comentários Paginação Flexível

Copy

1

2curl --request GET \

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

4

Comentários Paginação Flexível no Contexto do Usuário

Copy

1

2curl --request GET \

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

4

Comentários Paginação Flexível no Contexto do Usuário Apenas Comentários de Nível Superior

Copy

1

2curl --request GET \

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

4

Comentários como Árvore

É possível obter os comentários retornados como uma árvore, com paginação contando apenas os comentários de nível superior.

Comentários Como Árvore no Contexto do Usuário

Copy

1

2curl --request GET \

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

4

Quer obter apenas os comentários de nível superior e os filhos imediatos? Aqui está uma maneira:

Comentários Como Árvore com Profundidade Máxima

Copy

1

2curl --request GET \

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

4

No entanto, na sua UI você pode precisar saber se deve mostrar um botão "mostrar respostas" em cada comentário. Ao buscar comentários via uma árvore há uma propriedade hasChildren marcada nos comentários quando aplicável.

Comentários como Árvore, Buscando por Hashtag

É possível buscar por hashtag usando a API, em todo o seu tenant (não limitado a uma página, ou urlId).

Neste exemplo, omitimos urlId e buscamos por múltiplas hashtags. A API retornará apenas comentários que possuam todas as hashtags solicitadas.

Comentários Como Árvore no Contexto do Usuário, Por Hashtag

Copy

1

2curl --request GET \

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

4

Estrutura da Requisição de Comentários

Estrutura da Requisição de Comentários

Copy

1

2interface CommentsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** O urlId (URL da página ou ID do artigo) ao qual os comentários estão associados. **/

6 urlId?: string

7 /** Limita os comentários retornados por este usuário. **/

8 userId?: string

9 /** Use isso para buscar por hashtag. Para aprofundar na interseção de múltiplas hashtags, use &hashTag=a&hashTag=b. **/

10 hashTag?: string

11 /** A direção de ordenação. O padrão é MR (Mais Relevante). Outras opções são OF (Mais Antigos Primeiro) e NF (Mais Recentes Primeiro). **/

12 direction?: 'MR' | 'OF' | 'NF'

13 /** Paginação Precalculada: A página a buscar, começando em 0. Passe -1 para todos os comentários (até 250). **/

14 page?: number

15 /** Paginação Flexível: Quantos comentários devemos retornar? **/

16 limit?: number

17 /** Paginação Flexível: Quantos comentários filhos devemos retornar para cada pai? **/

18 limitChildren?: number

19 /** Paginação Flexível: Quantos comentários devemos pular? **/

20 skip?: number

21 /** Paginação Flexível: Quantos comentários filhos devemos pular para cada pai? **/

22 skipChildren?: number

23 /** Para determinar comentários bloqueados e sinalizados. **/

24 contextUserId?: string

25 /** Para determinar comentários bloqueados e sinalizados. **/

26 anonUserId?: string

27 /** Para buscar comentários filhos. **/

28 parentId?: string

29 /** Para buscar como árvore. **/

30 asTree?: boolean

31 /** Até que profundidade da árvore devemos retornar dados? 0 não retorna filhos. 1 retorna filhos imediatos, etc. **/

32 maxTreeDepth?: number

33}

34

Estrutura da Resposta de Comentários

Estrutura da Resposta de Comentários

Copy

1

2interface CommentsResponse {

3 status: 'success' | 'failed'

4 /** Incluído em caso de falha. **/

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

6 /** Incluído em caso de falha. **/

7 reason?: string

8 /** Os comentários! **/

9 comments: Comment[]

10}

11

Dicas úteis

ID da URL

Provavelmente você quer usar a API Comment com o parâmetro urlId. Você pode chamar a API Pages primeiro, para ver como são os valores de urlId disponíveis para você.

Ações anônimas

Para comentários anônimos, provavelmente você quer passar anonUserId ao buscar comentários, e ao realizar sinalizações e bloqueios.

(!) Isso é obrigatório em muitas lojas de aplicativos, pois os usuários devem poder sinalizar conteúdo criado por usuários que eles podem ver, mesmo que não estejam logados. Não fazer isso pode fazer com que seu aplicativo seja removido da referida loja.

Comentários não sendo retornados

Verifique se seus comentários estão aprovados e não são spam.

Esta API permite buscar um único comentário por id.

Exemplo cURL: Obter comentário por ID

Copy

1

2curl --request GET \

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

4

Estrutura da Requisição: Obter comentário por ID

Copy

1

2interface CommentsGetByIdQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Estrutura da Resposta: Obter comentário por ID

Copy

1

2interface CommentGetByIdResponse {

3 status: 'success' | 'failed'

4 /** Incluído em caso de falha. **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'missing-id'

6 /** Incluído em caso de falha. **/

7 reason?: string

8 /** O comentário! **/

9 comment?: Comment

10}

11

Este endpoint da API fornece a capacidade de criar comentários.

Casos de uso comuns incluem UIs personalizadas, integrações ou importações.

Notas:

• Esta API pode atualizar o widget de comentários "live" se desejado (isso aumenta o creditsCost de 1 para 2).
• Esta API criará automaticamente objetos de usuário em nosso sistema se o email for fornecido.
• Tentar salvar dois comentários com emails diferentes, mas o mesmo nome de usuário, resultará em um erro para o segundo comentário.
• Se você estiver especificando parentId, e um comentário filho tiver notificationSentForParent como false, enviaremos notificações para o comentário pai. Isso é feito a cada hora (agrupamos as notificações para diminuir o número de emails enviados).
• Se você quiser enviar emails de boas-vindas ao criar usuários, ou emails de verificação de comentário, defina sendEmails como true nos parâmetros de consulta.
• Comentários criados via esta API aparecerão nas páginas de Analytics e Moderation do aplicativo de administração.
• Palavrões ainda são mascarados nos nomes dos comentaristas e no texto do comentário se a configuração estiver ativada.
• Comentários criados via esta API ainda podem ser verificados quanto a spam, se desejado.
• Configurações como comprimento máximo do comentário, se configuradas via a página de administração Customization Rule, serão aplicadas aqui.

Os dados mínimos necessários para enviar que serão exibidos no widget de comentários são os seguintes:

Exemplo mínimo de POST cURL de Comentário

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true' \

4 --header 'Content-Type: application/json' \

5 --data '{

6 "approved": true,

7 "comment": "some-comment",

8 "commenterName": "some-commenter-name",

9 "date": 1622644382148,

10 "urlId": "some-place",

11 "url": "https://exmaple.com/some-page",

12 "verified": true

13}'

14

Uma requisição mais realista pode ser:

Exemplo de POST cURL para Comentário

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true&doSpamCheck=true' \

4 --header 'Content-Type: application/json' \

5 --data '{

6 "approved": true,

7 "avatarSrc": "https://static.fastcomments.com/1605337537848-DSC_0841.JPG",

8 "comment": "some-comment",

9 "commenterName": "some-commenter-name",

10 "commenterEmail": "fordperfect@spaceship.com",

11 "date": 1622644382148,

12 "isSpam": false,

13 "locale": "en_us",

14 "notificationSentForParent": true,

15 "notificationSentForParentTenant": true,

16 "reviewed": true,

17 "urlId": "some-place",

18 "url": "https://exmaple.com/some-page",

19 "verified": true,

20 "votes": 1,

21 "votesUp": 2,

22 "votesDown": 1,

23 "ip": "123.456.789.000"

24}'

25

Estrutura da Requisição POST de Comentário

Copy

1

2interface CommentPostQueryParams {

3 tenantId: string

4 API_KEY: string

5 doSpamCheck?: 'true' | 'false'

6 /** Se o comentário deve aparecer "live" para usuários visualizando instâncias do widget de comentários com o mesmo urlId. NOTA: Dobra o custo de créditos de 1 para 2. **/

7 isLive?: 'true' | 'false'

8 sendEmails?: 'true' | 'false'

9 populateNotifications?: 'true' | 'false'

10}

11

Estrutura da Resposta POST de Comentário

Copy

1

2

3interface CommentPostResponse {

4 status: 'success' | 'failed'

5 /** Incluído em caso de falha. **/

6 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';

7 /** Incluído em caso de falha. **/

8 reason?: string

9 /** O comentário criado. **/

10 comment?: Comment

11 /** O usuário associado, que pode ou não já ter existido. **/

12 user?: User

13}

14

Este endpoint de API fornece a capacidade de atualizar um único comentário.

Observações:

• Esta API pode atualizar o widget de comentários "ao vivo" se desejado (isso aumenta o creditsCost base de 1 para 2).
  • Isso pode tornar a migração de comentários entre páginas "ao vivo" (alterando urlId).
  • Migrações custam 2 créditos adicionais, pois as páginas são pré-calculadas e isso é intensivo em CPU.
• Diferente da API de criação, esta API NÃO criará automaticamente objetos de usuário em nosso sistema se o email for fornecido.
• Comentários atualizados via esta API ainda podem ser verificados quanto a spam, se desejado.
• Configurações como comprimento máximo do comentário, se configuradas através da página de administração de Regras de Personalização, serão aplicadas aqui.
• Para permitir que os usuários atualizem o texto de seus comentários, você pode simplesmente especificar comment no corpo da requisição. Nós geraremos o commentHTML resultante.
  • Se você definir tanto comment quanto commentHTML, não geraremos o HTML automaticamente.
  • Se o usuário adicionar menções ou hashtags em seu novo texto, elas ainda serão processadas como na API POST.
• Ao atualizar commenterEmail em um comentário, é melhor também especificar userId. Caso contrário, você deve garantir que o usuário com este email pertença ao seu tenant, ou a requisição falhará.
• Se o comentário de destino estiver bloqueado (isLocked: true), a requisição será rejeitada com code: 'locked'. Desbloqueie o comentário primeiro, atualize-o e, se desejado, bloqueie novamente.

Exemplo mínimo de cURL para PATCH de comentário

Copy

1

2curl --request PATCH \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true' \

4 --header 'Content-Type: application/json' \

5 --data '{

6 "comment": "some-new-comment-text"

7}'

8

Estrutura da requisição PATCH de comentário

Copy

1

2interface CommentPatchQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** O usuário realizando a atualização. Se desejado, pode ser usado para verificar se ele pode editar o comentário. **/

6 contextUserId?: string

7 /** Devemos verificar se o novo comentário parece spam? **/

8 doSpamCheck?: 'true' | 'false'

9 /** Se o comentário deve aparecer "ao vivo" para usuários visualizando instâncias do widget de comentários com o mesmo urlId. NOTA: Dobra o custo em créditos de 1 para 2. **/

10 isLive?: 'true' | 'false'

11}

12

Estrutura da resposta PATCH de comentário

Copy

1

2

3interface CommentPatchResponse {

4 status: 'success' | 'failed'

5 /** Incluído em caso de falha. **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-comment' | 'comment-too-big' | 'hash-tags-readonly' | 'mentions-readonly' | 'invalid-user' | 'unauthorized' | 'invalid-date' | 'invalid-name' | 'invalid-name-is-email' | 'banned' | 'invalid-email' | 'invalid-input' | 'missing-id' | 'not-found' | 'locked'

7 /** Incluído em caso de falha. **/

8 reason?: string

9}

10

Este endpoint da API permite excluir um comentário.

Notas:

• Esta API pode atualizar o widget de comentários "ao vivo" se desejado (isso aumenta creditsCost de 1 para 2).
• Esta API excluirá todos os comentários filhos.
• Se o comentário alvo estiver bloqueado (isLocked: true), a requisição é rejeitada com code: 'locked'. Desbloqueie o comentário primeiro, então exclua.

Exemplo cURL para DELETE de Comentário

Copy

1

2curl --request DELETE \

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

4 --header 'Content-Type: application/json'

5

Estrutura da Requisição DELETE de Comentário

Copy

1

2interface CommentDeleteQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** O usuário que está realizando a atualização. Se desejado, pode ser usado para verificar se ele pode excluir o comentário. **/

6 contextUserId?: string

7 /** Se o comentário deve ser excluído "ao vivo" para usuários visualizando instâncias do widget de comentários com o mesmo urlId. NOTA: Dobra o custo de créditos de 1 para 2. **/

8 isLive?: 'true' | 'false'

9}

10

Estrutura da Resposta DELETE de Comentário

Copy

1

2

3interface CommentDeleteResponse {

4 status: 'success' | 'failed'

5 /** Incluído em caso de falha. **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'locked'

7 /** Incluído em caso de falha. **/

8 reason?: string

9}

10

Este endpoint da API permite sinalizar um comentário para um usuário específico.

Notas:

• Essa chamada deve sempre ser feita no contexto de um usuário. O usuário pode ser um FastComments.com User, SSO User, ou Tenant User.
• Se um limite de sinalizações-para-ocultar estiver definido, o comentário será automaticamente ocultado ao vivo depois de ter sido sinalizado o número de vezes definido.
• Depois que for automaticamente desaprovado (oculto) - o comentário só poderá ser re-aprovado por um administrador ou moderador. Remover a sinalização não re-aprovará o comentário.

Exemplo cURL de sinalização de comentário

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/flag?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \

4 --header 'Content-Type: application/json'

5

Para sinalização anônima, devemos especificar um anonUserId. Isso pode ser um ID que representa a sessão anônima, ou um UUID aleatório. Isso nos permite suportar a sinalização e a remoção da sinalização de comentários mesmo que um usuário não esteja logado. Dessa forma, o comentário pode ser marcado como sinalizado quando os comentários são buscados com o mesmo anonUserId.

Exemplo cURL de sinalização de comentário anônimo

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/flag?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \

4 --header 'Content-Type: application/json'

5

Estrutura da Requisição de Sinalização de Comentário

Copy

1

2interface CommentFlagQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7}

8

Estrutura da Resposta de Sinalização de Comentário

Copy

1

2

3interface CommentFlagResponse {

4 status: 'success' | 'failed'

5 /** Incluído em caso de falha. **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id'

7 /** Incluído em caso de falha. **/

8 reason?: string

9 /** O comentário foi desaprovado (oculto) devido a ter sido sinalizado muitas vezes? **/

10 wasUnapproved?: boolean;

11}

12

Este endpoint da API fornece a capacidade de remover a sinalização (un-flag) de um comentário para um usuário específico.

Observações:

• Esta chamada deve sempre ser feita no contexto de um usuário. O usuário pode ser um FastComments.com User, SSO User, ou Tenant User.
• Após um comentário ser desaprovado automaticamente (oculto) - o comentário só pode ser reaprovado por um administrador ou moderador. Remover a sinalização (un-flagging) não irá reaprovar o comentário.

Exemplo cURL de remoção de sinalização de comentário

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-flag?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \

4 --header 'Content-Type: application/json'

5

Para sinalização anônima, devemos especificar um anonUserId. Isso pode ser um ID que representa a sessão anônima, ou um UUID aleatório.

Exemplo cURL de remoção de sinalização de comentário anônimo

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-flag?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \

4 --header 'Content-Type: application/json'

5

Estrutura da Requisição de Remoção de Sinalização de Comentário

Copy

1

2interface CommentFlagQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7}

8

Estrutura da Resposta de Remoção de Sinalização de Comentário

Copy

1

2

3interface CommentUnFlagResponse {

4 status: 'success' | 'failed'

5 /** Incluído em caso de falha. **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id'

7 /** Incluído em caso de falha. **/

8 reason?: string

9}

10

Este endpoint da API fornece a capacidade de bloquear um usuário que escreveu um determinado comentário. Ele suporta bloqueio de comentários escritos por FastComments.com Users, SSO Users e Tenant Users.

Ele suporta um parâmetro de corpo commentIdsToCheck para verificar se quaisquer outros comentários potencialmente visíveis no cliente devem ser bloqueados/desbloqueados após esta ação ser realizada.

Notas:

• Esta chamada deve sempre ser feita no contexto de um usuário. O usuário pode ser um FastComments.com User, SSO User ou Tenant User.
• O userId na requisição é o usuário que está fazendo o bloqueio. Por exemplo: User A quer bloquear User B. Passe userId=User A e o id do comentário que User B escreveu.
• Comentários completamente anônimos (sem user id, sem email) não podem ser bloqueados e um erro será retornado.

Exemplo cURL de bloqueio de comentário

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/block?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \

4 --header 'Content-Type: application/json'

5

Para bloqueio anônimo, devemos especificar um anonUserId. Isso pode ser um ID que representa a sessão anônima, ou um UUID aleatório. Isso nos permite suportar o bloqueio de comentários mesmo que um usuário não esteja logado, buscando os comentários com o mesmo anonUserId.

Exemplo cURL de bloqueio de comentário anônimo

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/block?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \

4 --header 'Content-Type: application/json'

5

Estrutura da requisição de bloqueio de comentário

Copy

1

2interface CommentBlockQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7 commentIdsToCheck?: string[]

8}

9

Estrutura da resposta de bloqueio de comentário

Copy

1

2

3interface CommentBlockResponse {

4 status: 'success' | 'failed'

5 /** Incluído em caso de falha. **/

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

7 /** Incluído em caso de falha. **/

8 reason?: string

9 /** Se commentIdsToCheck estiver definido, entradas neste mapa com true também são bloqueadas. **/

10 commentStatuses?: Record<string, boolean>;

11}

12

Este endpoint da API fornece a capacidade de desbloquear um usuário que escreveu um determinado comentário. Ele suporta o desbloqueio de comentários escritos por FastComments.com Users, SSO Users, and Tenant Users.

Ele suporta um parâmetro de corpo commentIdsToCheck para verificar se quaisquer outros comentários potencialmente visíveis no cliente devem ser bloqueados/desbloqueados após esta ação ser executada.

Notas:

• Esta chamada deve sempre ser feita no contexto de um usuário. O usuário pode ser um FastComments.com User, SSO User, ou Tenant User.
• O userId na requisição é o usuário que está realizando o desbloqueio. Por exemplo: User A quer desbloquear User B. Passe userId=User A e o id do comentário que User B escreveu.
• Comentários completamente anônimos (sem user id, sem email) não podem ser bloqueados e um erro será retornado.

Exemplo cURL de Desbloqueio de Comentário

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-block?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \

4 --header 'Content-Type: application/json'

5

Exemplo cURL de Desbloqueio de Comentário Anônimo

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-block?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \

4 --header 'Content-Type: application/json'

5

Estrutura da Requisição de Desbloqueio de Comentário

Copy

1

2interface CommentUnBlockQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7 commentIdsToCheck?: string[]

8}

9

Estrutura da Resposta de Desbloqueio de Comentário

Copy

1

2

3interface CommentUnBlockResponse {

4 status: 'success' | 'failed'

5 /** Incluído em caso de falha. **/

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

7 /** Incluído em caso de falha. **/

8 reason?: string

9 /** Se commentIdsToCheck estiver definido, entradas neste mapa com true ainda estão bloqueadas. Se false, você pode querer reexibir os comentários para o usuário para que ele não precise atualizar. **/

10 commentStatuses?: Record<string, boolean>;

11}

12

EmailTemplates individuais podem ser obtidos pelo seu id correspondente (NÃO emailTemplateId).

Exemplo cURL de EmailTemplate por ID

Copy

1

2curl --request GET \

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

4

Estrutura da Requisição de EmailTemplate por ID

Copy

1

2interface EmailTemplatesByIdRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Estrutura da Resposta de EmailTemplate por ID

Copy

1

2interface EmailTemplateResponse {

3 status: 'success' | 'failed'

4 /** Incluído em caso de falha. **/

5 code?: 'internal' | 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found'

6 /** Incluído em caso de falha. **/

7 reason?: string

8 emailTemplate?: EmailTemplate | null

9}

10

Esta API usa paginação, fornecida pelo parâmetro de consulta page. EmailTemplates são retornados em páginas de 100, ordenados por createdAt e depois por id.

Exemplo cURL de EmailTemplate

Copy

1

2curl --request GET \

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

4

Estrutura de Requisição de EmailTemplate

Copy

1

2interface EmailTemplatesRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** A página a ser buscada, começando em 0. **/

6 page: number

7}

8

Estrutura de Resposta de EmailTemplate

Copy

1

2interface EmailTemplatesResponse {

3 status: 'success' | 'failed'

4 /** Incluído em caso de falha. **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'

6 /** Incluído em caso de falha. **/

7 reason?: string

8 emailTemplates: EmailTemplate[]

9}

10

Este endpoint da API permite atualizar um modelo de e-mail especificando apenas o id e os atributos a serem atualizados.

Observe que todas as mesmas validações para criar um modelo também se aplicam, por exemplo:

• O modelo deve renderizar. Isso é verificado a cada atualização.
• Não é permitido ter modelos duplicados para o mesmo domínio (caso contrário, um deles seria ignorado silenciosamente).

Exemplo cURL PATCH EmailTemplate

Copy

1

2curl --request PATCH \

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

4 --header 'Content-Type: application/json' \

5 --data '{

6 "displayName": "Some New Name",

7}'

8

Estrutura da Requisição PATCH EmailTemplate

Copy

1

2interface EmailTemplatePatchQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Estrutura de Resposta PATCH EmailTemplate

Copy

1

2

3interface EmailTemplatePatchResponse {

4 status: 'success' | 'failed'

5 /** Incluído em caso de falha. **/

6 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';

7 /** Incluído em caso de falha. **/

8 reason?: string

9 /** O modelo de e-mail atualizado. **/

10 emailTemplate?: EmailTemplate

11}

12

Este endpoint de API fornece a capacidade de criar modelos de e-mail.

Observações:

• Você não pode ter vários modelos com o mesmo emailTemplateId no mesmo domínio.
• Mas você pode ter um modelo curinga (domain = * e um modelo específico de domínio para o mesmo emailTemplateId).
• Especificar domain só é relevante se você tiver domínios diferentes, ou quiser usar modelos específicos para testes (domain definido como localhost etc).
• Se você especificar domain, ele deve corresponder a um DomainConfig. Em caso de erro, uma lista de domínios válidos é fornecida.
• A sintaxe do modelo é EJS e é renderizada com um tempo limite de 500ms. O P99 de renderização é <5ms, então se você atingir 500ms algo está errado.
• Seu modelo deve renderizar com o testData fornecido para ser salvo. Erros de renderização são agregados e reportados no painel (em breve disponível via API).

Os dados mínimos necessários para adicionar um modelo são os seguintes:

Exemplo mínimo de cURL POST de EmailTemplate

Copy

1

2curl --request POST \

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

4 --header 'Content-Type: application/json' \

5 --data '{

6 "emailTemplateId": "comment-user-mention",

7 "displayName": "I'm a custom template.",

8 "ejs": "This is an @mention notification! My name is <%= comment.commenterName %>."

9}'

10

Você pode querer ter modelos por site, nesse caso você define domain:

Exemplo de cURL POST de EmailTemplate

Copy

1

2curl --request POST \

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

4 --header 'Content-Type: application/json' \

5 --data '{

6 "emailTemplateId": "comment-user-mention",

7 "displayName": "I'm a custom template.",

8 "ejs": "This is some email content!",

9 "domain": "somespecificsite.com",

10}'

11

Estrutura da requisição POST de EmailTemplate

Copy

1

2interface EmailTemplatePostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Estrutura da resposta POST de EmailTemplate

Copy

1

2

3interface EmailTemplatePostResponse {

4 status: 'success' | 'failed'

5 /** Incluído em caso de falha. **/

6 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';

7 /** Incluído em caso de falha. **/

8 reason?: string

9 /** O modelo criado. **/

10 emailTemplate?: EmailTemplate

11}

12

Este endpoint da API permite visualizar modelos de e-mail.

Exemplo mínimo de cURL POST para pré-visualização de EmailTemplate

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/email-templates/render?tenantId=demo&API_KEY=DEMO_API_SECRET' \

4 --header 'Content-Type: application/json' \

5 --data '{

6 "emailTemplateId": "comment-user-mention",

7 "displayName": "I'm a custom template.",

8 "ejs": "This is an @mention notification! My name is <%= comment.commenterName %>."

9}'

10

Estrutura da requisição POST de EmailTemplate

Copy

1

2interface EmailTemplatePostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Estrutura da resposta POST de EmailTemplate

Copy

1

2

3interface EmailTemplatePostResponse {

4 status: 'success' | 'failed'

5 /** Incluído em caso de falha. **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'unexpected-param' | 'does-not-render';

7 /** Incluído em caso de falha. **/

8 reason?: string

9 /** O HTML renderizado em caso de sucesso. **/

10 html?: string

11}

12

Esta rota remove um único EmailTemplate por id.

Exemplo de cURL para remoção de EmailTemplate

Copy

1

2curl --request DELETE \

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

4

Estrutura da Requisição de Remoção de EmailTemplate

Copy

1

2interface EmailTemplateRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Estrutura da Resposta de Remoção de EmailTemplate

Copy

1

2interface EmailTemplateDeleteResponse {

3 status: 'success' | 'failed'

4 /** Incluído em caso de falha. **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized'

6 /** Incluído em caso de falha. **/

7 reason?: string

8}

9

Busca posts em um feed, mais recentes primeiro. A paginação é baseada em cursor: passe o _id do último post que você recebeu como afterId para obter a próxima página.

Custa um crédito por cada dez posts retornados, com um mínimo de um crédito.

Exemplo cURL do FeedPost

Copy

1

2curl --request GET \

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

4

Estrutura de Requisição do FeedPost

Copy

1

2interface FeedPostsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Retorna posts após este ID de post. Omitir para a primeira página. **/

6 afterId?: string

7 /** Padrão 10. Máximo 1000. **/

8 limit?: number

9 /** Retorna apenas posts com estas tags. Repita o parâmetro para mais de uma tag. **/

10 tags?: string[]

11}

12

Estrutura de Resposta do FeedPost

Copy

1

2interface FeedPostsResponse {

3 status: 'success' | 'failed'

4 /** Incluído em caso de falha. **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'limit-invalid' | 'internal'

6 /** Incluído em caso de falha. **/

7 reason?: string

8 feedPosts: FeedPost[]

9}

10

Esta rota cria um único FeedPost. Cada postagem tem um autor, portanto fromUserId é obrigatório e deve ser o ID de um usuário FastComments ou SSO existente na conta.

Exemplo cURL de Criação de FeedPost

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/feed-posts?tenantId=demo&isLive=true&API_KEY=DEMO_API_SECRET' \

4 --header 'Content-Type: application/json' \

5 --data '{

6 "fromUserId": "some-user-id",

7 "title": "Release 2.0 is out",

8 "contentHTML": "<p>Read the notes and tell us what you think.</p>",

9 "tags": ["releases"],

10 "links": [

11 {

12 "url": "https://example.com/releases/2.0",

13 "title": "Release notes",

14 "description": "Everything that changed in 2.0."

15 }

16 ]

17}'

18

Estrutura de Requisição de Criação de FeedPost

Copy

1

2interface FeedPostPostQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Envia a postagem para feeds que estão abertos em um navegador agora. O padrão é false. **/

6 isLive?: boolean

7 /** Executa a postagem através do mecanismo de spam antes de salvar. O padrão é false. **/

8 doSpamCheck?: boolean

9 /** Ignora a verificação de conteúdo repetido que ocorre como parte do doSpamCheck. O padrão é false. **/

10 skipDupCheck?: boolean

11 /** Até 256 caracteres. Ecoado para ouvintes ao vivo para que um cliente possa ignorar sua própria transmissão. **/

12 broadcastId?: string

13}

14

15interface FeedPostPostBody {

16 /** Obrigatório. Um ID de usuário FastComments ou SSO. **/

17 fromUserId: string

18 title?: string

19 /** HTML. Sanitizado ao salvar. **/

20 contentHTML?: string

21 /** Substitui o nome de exibição obtido do usuário. **/

22 fromUserDisplayName?: string

23 tags?: string[]

24 media?: FeedPostMediaItem[]

25 links?: FeedPostLink[]

26 meta?: Record<string, string>

27}

28

Estrutura de Resposta de Criação de FeedPost

Copy

1

2interface FeedPostPostResponse {

3 status: 'success' | 'failed'

4 /** Incluído em caso de falha. **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-from-user-id' | 'invalid-user' | 'broadcast-id-too-long' | 'spam-blocked' | 'user-rate-limited' | 'internal'

6 /** Incluído em caso de falha. **/

7 reason?: string

8 feedPost?: FeedPost; // Retornamos a postagem completa criada em caso de sucesso.

9}

10

Esta rota atualiza um único FeedPost. Envie apenas os campos que você deseja alterar.

Exemplo cURL de Atualização de FeedPost

Copy

1

2curl --request PATCH \

3 --url 'https://fastcomments.com/api/v1/feed-posts/some-post-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \

4 --header 'Content-Type: application/json' \

5 --data '{

6 "title": "Release 2.0.1 is out",

7 "tags": ["releases", "hotfix"]

8}'

9