API di commenti in tempo reale

Utilizzo delle risorse

Va notato che il recupero dei dati dall'API viene conteggiato come utilizzo sul tuo account.

Ogni risorsa elencherà quale sia quell'utilizzo nella sua sezione.

Alcune risorse costano di più da servire rispetto ad altre. Ogni endpoint ha un costo fisso di crediti per chiamata API. Per alcuni endpoint, il numero di crediti varia in base alle opzioni e alle dimensioni delle risposte.

L'utilizzo dell'API può essere verificato nella pagina Billing Analytics ed è aggiornato ogni pochi minuti.

Nota!

Consigliamo di leggere prima la documentazione delle Pagine, per aiutare a limitare la confusione nella determinazione dei valori da passare per urlId nell'API dei Commenti.

Webhook

Le sottoscrizioni ai webhook hanno la propria guida. POST, GET e DELETE /api/v1/webhooks, e GET /api/v1/webhooks/sample-payloads, sono documentati in Managing Subscriptions via API, e i payload degli eventi in Webhook Structures.

FastComments è un server di autorizzazione OAuth 2.1. Un'applicazione può ottenere un token associato a un account FastComments e usarlo su ogni endpoint in questa guida al posto di una chiave API. È così che l'app Zapier, il server MCP e altre integrazioni di terze parti si connettono.

I token vengono emessi tramite il flusso di codice di autorizzazione con PKCE. Non esistono grant di credenziali client né grant impliciti.

Scoperta

Le posizioni degli endpoint, i grant supportati e i metodi di autenticazione sono pubblicati all'URL standard dei metadati:

Metadata del Server di Autorizzazione

Copy

1

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

3

Gli endpoint che descrive:

Endpoint 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

Gli account nella regione EU usano https://eu.fastcomments.com come emittente, con gli stessi percorsi.

Registrazione di un client

Un client ha bisogno di un client_id e di un redirect_uri registrato prima di poter avviare il flusso. Ci sono due modi per ottenerne uno:

• Registrazione dinamica del client. POST /oauth/register con un corpo JSON secondo RFC 7591 (redirect_uris, client_name, client_uri, logo_uri, token_endpoint_auth_method). La risposta contiene il client_id e, per i client confidenziali, il client_secret. La registrazione è non autenticata e limitata per IP.
• Documento di metadati del client ID. Il client utilizza un URL https che controlla come suo client_id. FastComments recupera quell'URL e legge gli stessi campi di metadati. Non è necessaria alcuna chiamata di registrazione.

Le applicazioni partner elencate nella dashboard di FastComments, come Zapier, sono registrate direttamente da FastComments. Contatta il supporto se stai creando un'inserzione di marketplace e hai bisogno di un client di prima parte.

Scope

Scope

Copy

1

2read GET and HEAD requests

3write every other method

4

Una richiesta che non specifica alcuno scope ottiene entrambi. L'utente vede gli scope richiesti nella pagina di consenso. Una richiesta per uno scope diverso da questi due fallisce con invalid_scope.

Passo 1 - Richiesta di autorizzazione

Invia il browser dell'utente all'endpoint di autorizzazione. PKCE con il metodo S256 è obbligatorio per ogni client.

Richiesta di Autorizzazione

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

Parametri della Richiesta di Autorizzazione

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

L'utente accede a FastComments se necessario e vede una pagina di consenso che indica la tua applicazione, l'account a cui sarà collegata e gli scope richiesti. L'utente deve possedere il permesso API Admin su quell'account; chiunque altro vede un errore di permesso invece del modulo di consenso. L'approvazione reindirizza il browser al tuo redirect_uri con code e state. Il rifiuto reindirizza con error=access_denied.

Il codice di autorizzazione è valido per 10 minuti e può essere scambiato una sola volta. Un secondo scambio dello stesso codice revoca tutti i token prodotti dal primo scambio.

Passo 2 - Richiesta di token

Scambia il codice per i token. Il corpo è codificato come form. I client confidenziali si autenticano con client_secret_basic (HTTP Basic) o client_secret_post (segreto nel corpo). I client pubblici inviano solo client_id.

Esempio cURL della Richiesta di Token

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 della Richiesta di 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

Struttura della Risposta del 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

Gli errori seguono RFC 6749: un corpo JSON con error e error_description, HTTP 400 per invalid_request, invalid_grant, invalid_scope, invalid_target e unsupported_grant_type, HTTP 401 per invalid_client, HTTP 429 quando limitati per velocità.

Passo 3 - Chiamare l'API

Invia il token di accesso come token bearer. Il tenant è implicito nel token, quindi tenantId è opzionale. Se fornito deve corrispondere al token altrimenti la richiesta fallisce.

Esempio cURL del Token Bearer

Copy

1

2curl --request GET \

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

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

5

GET /api/v1/me restituisce il tenant, l'utente autorizzatore e gli scope concessi, il che lo rende la chiamata giusta per un test di connessione. Una richiesta con un token scaduto o revocato restituisce HTTP 401. Una richiesta il cui metodo richiede uno scope non posseduto dal token restituisce HTTP 403.

Passo 4 - Aggiornamento

Esempio cURL della Richiesta di Refresh

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 della Richiesta di 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

La risposta ha la stessa struttura dello scambio del codice. I refresh token ruotano: ogni refresh restituisce un nuovo refresh_token e revoca quello vecchio dopo una finestra di grazia di 30 secondi per richieste concorrenti. Presentare un refresh token ruotato più di 30 secondi fa sì che venga trattato come replay e revoca l'intero grant. Le applicazioni partner registrate da FastComments sono esenti dalla rotazione e ricevono lo stesso refresh token con la scadenza estesa di altri 30 giorni.

Un refresh verifica anche che l'utente autorizzatore mantenga ancora il permesso API Admin sull'account. In caso contrario, il grant è revocato e la risposta è invalid_grant.

Revoca

Esempio cURL della Richiesta di Revoca

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

Revocare un refresh token revoca tutti gli access token emessi dallo stesso grant. Revocare un access token revoca solo quel token. L'endpoint restituisce HTTP 200 con un oggetto JSON vuoto, indipendentemente dal fatto che il token sia stato trovato, secondo RFC 7009.

Gli utenti possono anche revocare una connessione da App connesse nella dashboard di FastComments. Tutti i token per quell'applicazione smettono di funzionare immediatamente.

Questa API aggrega documenti raggruppandoli (se viene fornito groupBy) e applicando più operazioni. Sono supportate diverse operazioni (ad es. sum, countDistinct, avg, ecc.).

Il costo è variabile. Ogni 500 oggetti scansionati costa 1 credito API.

La memoria massima consentita per chiamata API di default è 64MB, e per impostazione predefinita puoi avere una sola aggregazione in esecuzione alla volta. Se invii più aggregazioni simultaneamente, verranno messe in coda ed eseguite nell'ordine di invio. Le aggregazioni in attesa rimarranno in coda per un massimo di 60 secondi, dopodiché la richiesta scadrà. Le singole aggregazioni possono essere eseguite per un massimo di 5 minuti.

Se hai tenant gestiti, puoi aggregare tutte le risorse dei tenant figli in una singola chiamata passando il parametro di query parentTenantId.

Esempi

Esempio: Conteggio valori unici

Esempio cURL: Conteggio valori unici

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

Risposta: Conteggio valori unici

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

Esempio: Conteggio valori distinti

Esempio cURL: Conteggio valori distinti

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

Risposta:

Risposta: Conteggio valori distinti

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

Esempio: Somma dei valori di più campi

Esempio cURL: Somma dei valori

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

Risposta:

Risposta: Somma dei valori

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

Esempio: Media dei valori di più campi

Esempio cURL: Media dei valori

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

Risposta:

Risposta: Media dei valori

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

Esempio: Valori min/max di più campi

Esempio cURL: Valori min/max

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

Risposta:

Risposta: Valori min/max

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

Esempio: Conteggio valori unici di più campi

Esempio cURL: Conteggio valori unici

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

Risposta:

Risposta: Conteggio valori unici

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

Esempio: Creazione di query

Esempio cURL: Creazione di query

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

Risposta:

Risposta: Creazione di query

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

Esempio: Conteggio dei commenti in attesa di revisione

Esempio cURL: Conteggio commenti in attesa di revisione

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

Risposta:

Risposta: Conteggio commenti in attesa di revisione

Copy

1

2{

3 "status": "success",

4 "data": [

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

6 ],

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

8}

9

Esempio: Ripartizione dei commenti approvati, revisionati e spam

Esempio cURL: Ripartizione dei commenti

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

Risposta:

Risposta: Ripartizione dei commenti

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

Strutture

Struttura della richiesta Aggregate

Copy

1

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

3

4/** Un'operazione che verrà applicata a un campo */

5export interface AggregationOperation {

6 /** Il campo su cui operare */

7 field: string;

8 /** Il tipo di operazione */

9 op: AggregationOpType;

10 /** Alias opzionale per l'output; se non fornito, viene calcolato un alias predefinito */

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

Struttura della risposta 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

Le seguenti risorse possono essere aggregate:

• 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

Questa API utilizza la paginazione, fornita dai parametri skip, limit, before e after. Gli AuditLogs vengono restituiti in pagine di 1000 per impostazione predefinita, fino a un limit massimo di 10000, ordinati per when e id. Le pagine sono grandi perché questo endpoint viene in genere utilizzato per esportare la cronologia piuttosto che per sfogliarla interattivamente.

Ogni 100 log restituiti ha un costo di 1 credito.

Per impostazione predefinita, riceverai un elenco con gli elementi più recenti per primi. In questo modo, puoi effettuare il polling partendo da skip=0, paginando fino a trovare l'ultimo record che hai consumato.

In alternativa, puoi ordinare dal più vecchio al più recente, e paginare finché non ci sono più record.

L'ordinamento può essere effettuato impostando order su ASC o DESC. Il valore predefinito è DESC.

L'interrogazione per data è possibile tramite before e after come timestamp con millisecondi. before e after NON sono inclusivi, e ciascuno può essere utilizzato da solo.

Trovare cosa è successo a una persona

Ogni evento registra chi lo ha eseguito (username, userId, ip) e, separatamente, su cosa è stato eseguito. targetLabel è un'etichetta leggibile dall'utente per quell'oggetto, ad esempio jsmith (jsmith@example.com), e targetId è il suo id. Usa target per una corrispondenza di sottostringa senza distinzione tra maiuscole e minuscole sull'etichetta quando conosci il nome o l'email di una persona ma non il suo id.

Le eliminazioni acquisiscono l'etichetta al momento dell'evento, quindi un utente o un moderatore rimosso può ancora essere identificato dopo che il record sottostante è stato eliminato.

Tenant gestiti

Se il tuo tenant gestisce altri tenant, imposta includeManagedTenants=true per restituire gli eventi del tuo tenant e di ogni tenant che gestisce in un'unica risposta. Il tenantId di ogni log restituito ti indica da quale tenant proviene.

Esempio cURL di 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

Struttura della Richiesta AuditLog

Copy

1

2interface AuditLogsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 order?: 'ASC' | 'DESC'

6 /** Massimo 10000. Predefinito 1000. **/

7 limit?: number

8 skip?: number

9 before?: number

10 after?: number

11 /** Solo eventi eseguiti da questo username. **/

12 username?: string

13 /** Solo eventi da questo indirizzo IP. **/

14 ip?: string

15 /** Solo eventi di questo tipo. **/

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

17 /** Solo eventi per questa risorsa, ad es. User o Moderator. **/

18 resourceName?: string

19 /** Solo eventi il cui oggetto interessato ha questo id. **/

20 targetId?: string

21 /** Corrispondenza di sottostringa senza distinzione tra maiuscole e minuscole sull'etichetta dell'oggetto interessato. **/

22 target?: string

23 /** Restituisce anche gli eventi dai tenant gestiti da questo tenant. **/

24 includeManagedTenants?: boolean

25}

26

Struttura della Risposta AuditLog

Copy

1

2interface AuditLogsResponse {

3 status: 'success' | 'failed'

4 /** Incluso in caso di errore. **/

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

6 /** Incluso in caso di errore. **/

7 reason?: string

8 /** I log! **/

9 auditLogs: AuditLog[]

10}

11

Questo endpoint restituisce i batch job del tenant di ogni tipo, dal più recente al più vecchio, 100 per pagina. Usa type e status per restringere l'elenco e skip per paginarlo.

Esempio cURL per l'elenco 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

Struttura della richiesta per l'elenco BatchJob

Copy

1

2interface BatchJobsQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Only jobs of this type, for example migrate-pages. **/

6 type?: string

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

8 /** How many jobs to skip, for paging. A non-negative integer. **/

9 skip?: number

10}

11

Struttura della risposta per l'elenco BatchJob

Copy

1

2interface BatchJobsResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

6 /** Included on failure. **/

7 reason?: string

8 /** Newest first, at most 100. **/

9 batchJobs?: BatchJob[]

10}

11

Questa rotta restituisce lo stato, il progresso e, una volta terminato, il risultato di un batch job. Usala per monitorare un job avviato da POST /api/v1/pages/migrations o POST /api/v1/pages/migrations/:undoId/undo.

Un job è terminato quando il suo status è success o failed. Ogni chiamata costa 1 credito, quindi effettua il polling ogni pochi secondi anziché continuamente.

Esempio cURL BatchJob per 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

Struttura della Richiesta BatchJob per ID

Copy

1

2interface BatchJobQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Struttura della Risposta BatchJob per 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

Esempio di Job di Migrazione Pagina Terminato

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

Questa API viene utilizzata per ottenere i commenti da mostrare a un utente. Ad esempio, filtra automaticamente i commenti non approvati o contrassegnati come spam.

Paginazione

La paginazione può essere effettuata in uno dei due modi seguenti, a seconda dei requisiti di prestazioni e del caso d'uso:

1. Più veloce: Paginazione Precalcolata:
   1. È così che funziona FastComments quando si utilizzano i nostri widget e client predefiniti.
   2. Cliccare su "successivo" semplicemente incrementa il numero di pagina.
   3. Si può pensare a questo come a un recupero da un archivio chiave-valore.
   4. In questo modo, basta definire un parametro page a partire da 0 e una direzione di ordinamento come direction.
   5. Le dimensioni della pagina possono essere personalizzate tramite regole di personalizzazione.
2. Più flessibile: Paginazione Flessibile:
   1. In questo modo è possibile definire parametri limit e skip personalizzati. Non passare page.
   2. Anche la direction di ordinamento è supportata.
   3. limit è il numero totale da restituire dopo l'applicazione di skip.
      • Esempio: impostare skip = 200, limit = 100 quando page size = 100 e page = 2.
   4. I commenti figli contano comunque nella paginazione. È possibile aggirare questo problema utilizzando l'opzione asTree.
      • È possibile paginare i figli tramite limitChildren e skipChildren.
      • È possibile limitare la profondità dei thread restituiti tramite maxTreeDepth.

Thread

1. Quando si utilizza la Paginazione Precalcolata, i commenti sono raggruppati per pagina e i commenti nei thread influiscono sulla pagina complessiva.
   1. In questo modo, i thread possono essere determinati sul client in base a parentId.
   2. Ad esempio, con una pagina contenente un commento di primo livello e 29 risposte, impostando page=0 nell'API - si otterrà solo il commento di primo livello e i 29 figli.
2. Quando si utilizza la Paginazione Flessibile, è possibile definire un parametro parentId.
   1. Impostarlo su null per ottenere solo i commenti di primo livello.
   2. Quindi, per visualizzare i thread, chiamare nuovamente l'API passando parentId.
   3. Una soluzione comune è effettuare una chiamata API per i commenti di primo livello e poi effettuare chiamate API in parallelo per ottenere i commenti dei figli di ciascun commento.
3. NOVITÀ Da Febbraio 2023! Recupero come albero utilizzando &asTree=true.
   1. Si può pensare a questo come a una Paginazione Flessibile come Albero.
   2. Solo i commenti di primo livello contano nella paginazione.
   3. Impostare parentId=null per iniziare l'albero dalla radice (è necessario impostare parentId).
   4. Impostare skip e limit per la paginazione.
   5. Impostare asTree su true.
   6. Il costo in crediti aumenta del 2x, poiché il nostro backend deve fare molto più lavoro in questo scenario.
   7. Impostare maxTreeDepth, limitChildren e skipChildren come desiderato.

Spiegazione degli Alberi

Quando si utilizza asTree, può essere difficile ragionare sulla paginazione. Ecco un grafico utile:

Diagramma della Paginazione ad Albero

Recupero dei Commenti nel Contesto di un Utente

L'API /comments può essere utilizzata in due contesti, per diversi casi d'uso:

• Per restituire commenti ordinati e etichettati con informazioni per la creazione del proprio client.
  • In questo caso, definire un parametro di query contextUserId.
• Per recuperare commenti dal proprio backend per integrazioni personalizzate.
  • La piattaforma passerà per impostazione predefinita a questa modalità senza contextUserId.

Paginazione Precalcolata dei Commenti

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

Paginazione Flessibile dei Commenti

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

Paginazione Flessibile dei Commenti nel Contesto Utente

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

Paginazione Flessibile dei Commenti nel Contesto Utente Solo per Commenti di Primo Livello

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

Ottenere i Commenti come Albero

È possibile ottenere i commenti restituiti come albero, con la paginazione che conta solo i commenti di primo livello.

Commenti Come Albero nel Contesto Utente

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

Si vogliono ottenere solo i commenti di primo livello e i figli immediati? Ecco un modo:

Commenti Come Albero con Profondità Massima

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

Tuttavia, nella propria UI potrebbe essere necessario sapere se mostrare un pulsante "mostra risposte" su ciascun commento. Quando si recuperano i commenti come albero, esiste una proprietà hasChildren aggiunta ai commenti quando applicabile.

Ottenere i Commenti come Albero, Cercando per Hashtag

È possibile cercare per hashtag utilizzando l'API, su tutto il proprio tenant (non limitato a una pagina o a un urlId).

In questo esempio, omettiamo urlId e cerchiamo per più hashtag. L'API restituirà solo i commenti che hanno tutti gli hashtag richiesti.

Commenti Come Albero nel Contesto Utente, Per 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

Tutti i Parametri della Richiesta

Struttura della Richiesta dei Commenti

Copy

1

2interface CommentsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** The urlId (page url, or article id) the comments are associated with. **/

6 urlId?: string

7 /** Limit the comments returned by this user. **/

8 userId?: string

9 /** Use this to search by hashtag. To drill down to the intersection of multiple hashtags, do &hashTag=a&hashTag=b. **/

10 hashTag?: string

11 /** The sort direction. Default is MR (Most Relevant). Other options are OF (Oldest First) and NF (Newest First). **/

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

13 /** Precalculated Pagination: The page to fetch, starting with 0. Pass -1 for all comments (up to 250). **/

14 page?: number

15 /** Flexible Pagination: How many comments should we return? **/

16 limit?: number

17 /** Flexible Pagination: How many child comments should we return for each parent? **/

18 limitChildren?: number

19 /** Flexible Pagination: How many comments should we skip? **/

20 skip?: number

21 /** Flexible Pagination: How many child comments should we skip for each parent? **/

22 skipChildren?: number

23 /** For determining blocked and flagged comments. **/

24 contextUserId?: string

25 /** For determining blocked and flagged comments. **/

26 anonUserId?: string

27 /** For fetching child comments. **/

28 parentId?: string

29 /** For fetching as a tree. **/

30 asTree?: boolean

31 /** How far into the tree should we return data? 0 returns no children. 1 returns immediate children, etc. **/

32 maxTreeDepth?: number

33}

34

La Risposta

Struttura della Risposta dei Commenti

Copy

1

2interface CommentsResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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 /** Included on failure. **/

7 reason?: string

8 /** The comments! **/

9 comments: Comment[]

10}

11

Suggerimenti Utili

URL ID

Probabilmente si desidera utilizzare l'API Comment con il parametro urlId. È possibile chiamare prima l'API Pages, per vedere come sono i valori urlId disponibili.

Azioni Anonime

Per i commenti anonimi probabilmente si desidera passare anonUserId durante il recupero dei commenti e quando si effettuano segnalazioni e blocchi.

(!) Questo è richiesto da molti app store poiché gli utenti devono poter segnalare i contenuti creati dagli utenti che possono vedere, anche se non sono registrati. Non farlo può causare la rimozione della propria app da tale store.

Commenti Non Restituiti

Verificare che i propri commenti siano approvati e non siano spam.

Questa API fornisce la possibilità di recuperare un singolo commento tramite id.

Esempio cURL - Recupero commento per ID

Copy

1

2curl --request GET \

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

4

Struttura della richiesta - Recupero commento per ID

Copy

1

2interface CommentsGetByIdQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Struttura della risposta - Recupero commento per ID

Copy

1

2interface CommentGetByIdResponse {

3 status: 'success' | 'failed'

4 /** Incluso in caso di errore. **/

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

6 /** Incluso in caso di errore. **/

7 reason?: string

8 /** Il commento! **/

9 comment?: Comment

10}

11

Questo endpoint API consente di creare commenti.

Gli usi comuni sono interfacce utente personalizzate, integrazioni o importazioni.

Note:

• Questa API può aggiornare il widget dei commenti in "live" se desiderato (questo aumenta creditsCost da 1 a 2).
• Questa API creerà automaticamente oggetti utente nel nostro sistema se viene fornita un'email.
• Tentare di salvare due commenti con email diverse, ma lo stesso username, risulterà in un errore per il secondo commento.
• Se specifichi parentId, e un commento figlio ha notificationSentForParent impostato su false, invieremo notifiche per il commento genitore. Questo viene fatto ogni ora (raggruppiamo le notifiche insieme per diminuire il numero di email inviate).
• Se vuoi inviare email di benvenuto quando crei utenti, o email di verifica del commento, imposta sendEmails su true nei parametri di query.
• I commenti creati tramite questa API appariranno nelle pagine Analytics e Moderation dell'app di amministrazione.
• Le "bad words" sono ancora mascherate nei nomi dei commentatori e nel testo del commento se l'impostazione è attivata.
• I commenti creati tramite questa API possono comunque essere controllati per spam, se desiderato.
• La configurazione come la lunghezza massima del commento, se configurata tramite la pagina admin Customization Rule, si applicherà qui.

I dati minimi richiesti per l'invio che verranno visualizzati nel widget dei commenti, sono i seguenti:

Esempio minimo di richiesta cURL per POST commento

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

Una richiesta più realistica potrebbe apparire così:

Esempio di richiesta cURL per POST commento

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

Struttura della richiesta POST del commento

Copy

1

2interface CommentPostQueryParams {

3 tenantId: string

4 API_KEY: string

5 doSpamCheck?: 'true' | 'false'

6 /** Se il commento deve apparire "live" agli utenti che visualizzano istanze del widget dei commenti con lo stesso urlId. NOTA: raddoppia il costo in crediti da 1 a 2. **/

7 isLive?: 'true' | 'false'

8 sendEmails?: 'true' | 'false'

9 populateNotifications?: 'true' | 'false'

10}

11

Struttura della risposta POST del commento

Copy

1

2

3interface CommentPostResponse {

4 status: 'success' | 'failed'

5 /** Incluso in caso di errore. **/

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 /** Incluso in caso di errore. **/

8 reason?: string

9 /** Il commento creato. **/

10 comment?: Comment

11 /** L'utente associato, che potrebbe o meno essere già esistito. **/

12 user?: User

13}

14

Questo endpoint API fornisce la possibilità di aggiornare un singolo commento.

Note:

• Questa API può aggiornare il widget dei commenti "live" se desiderato (questo aumenta il creditsCost base da 1 a 2).
  • Questo può rendere "live" la migrazione dei commenti tra pagine (modificando urlId).
  • Le migrazioni costano 2 crediti aggiuntivi poiché le pagine vengono precalcolate e questo è intensivo per la CPU.
• A differenza dell'API di creazione, questa API NON creerà automaticamente oggetti utente nel nostro sistema se viene fornita un'email.
• I commenti aggiornati tramite questa API possono comunque essere controllati per spam, se desiderato.
• Configurazioni come la lunghezza massima del commento, se configurate tramite la pagina admin Customization Rule, si applicheranno qui.
• Per consentire agli utenti di aggiornare il testo del loro commento, puoi semplicemente specificare comment nel corpo della richiesta. Genereremo il relativo commentHTML.
  • Se definisci sia comment che commentHTML non genereremo automaticamente l'HTML.
  • Se l'utente aggiunge menzioni o hashtag nel nuovo testo, verranno comunque elaborati come nell'API POST.
• Quando si aggiorna commenterEmail su un commento, è consigliabile specificare anche userId. Altrimenti, devi assicurarti che l'utente con questa email appartenga al tuo tenant, altrimenti la richiesta fallirà.
• Se il commento target è bloccato (isLocked: true), la richiesta viene rifiutata con code: 'locked'. Sblocca prima il commento, aggiornalo, poi richiudilo se desiderato.

Esempio minimo di richiesta cURL PATCH per Commento

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

Struttura della richiesta PATCH per Commento

Copy

1

2interface CommentPatchQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** L'utente che esegue l'aggiornamento. Se desiderato può essere usato per verificare che possa modificare il commento. **/

6 contextUserId?: string

7 /** Dobbiamo controllare se il nuovo commento sembra spam? **/

8 doSpamCheck?: 'true' | 'false'

9 /** Se il commento dovrebbe apparire "live" agli utenti che visualizzano istanze del widget dei commenti con lo stesso urlId. NOTA: Raddoppia il costo in crediti da 1 a 2. **/

10 isLive?: 'true' | 'false'

11}

12

Struttura della risposta PATCH per Commento

Copy

1

2

3interface CommentPatchResponse {

4 status: 'success' | 'failed'

5 /** Incluso in caso di errore. **/

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 /** Incluso in caso di errore. **/

8 reason?: string

9}

10

Questo endpoint API consente di eliminare un commento.

Note:

• Questa API può aggiornare il comment widget "live" se desiderato (questo aumenta creditsCost da 1 a 2).
• Questa API eliminerà tutti i commenti figli.
• Se il commento target è bloccato (isLocked: true), la richiesta viene rifiutata con code: 'locked'. Sbloccare prima il commento, poi eliminarlo.

Esempio cURL DELETE Commento

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

Struttura della richiesta DELETE Commento

Copy

1

2interface CommentDeleteQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** L'utente che esegue l'aggiornamento. Se desiderato può essere usato per verificare che possa eliminare il commento. **/

6 contextUserId?: string

7 /** Se il commento dovrebbe essere eliminato "live" per gli utenti che visualizzano istanze del widget dei commenti con lo stesso urlId. NOTA: Raddoppia il costo in crediti da 1 a 2. **/

8 isLive?: 'true' | 'false'

9}

10

Struttura della risposta DELETE Commento

Copy

1

2

3interface CommentDeleteResponse {

4 status: 'success' | 'failed'

5 /** Incluso in caso di errore. **/

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

7 /** Incluso in caso di errore. **/

8 reason?: string

9}

10

Questo endpoint API fornisce la possibilità di segnalare (flaggare) un commento per un utente specifico.

Note:

• Questa chiamata deve sempre essere effettuata nel contesto di un utente. L'utente può essere un Utente FastComments.com, un Utente SSO o un Utente Tenant.
• Se è impostata una soglia di flag-per-nascondere, il commento verrà nascosto automaticamente in tempo reale dopo essere stato segnalato il numero definito di volte.
• Dopo che è stato automaticamente disapprovato (nascosto), il commento può essere riapprovato solo da un amministratore o un moderatore. La rimozione della segnalazione non riapproverà il commento.

Esempio cURL di segnalazione commento

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

Per la segnalazione anonima, dobbiamo specificare un anonUserId. Questo può essere un ID che rappresenta la sessione anonima, oppure un UUID casuale. Questo ci permette di supportare la segnalazione e la rimozione della segnalazione dei commenti anche se un utente non ha effettuato l'accesso. In questo modo, il commento può essere contrassegnato come segnalato quando i commenti vengono recuperati con lo stesso anonUserId.

Esempio cURL di segnalazione commento anonimo

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

Struttura della richiesta di segnalazione commento

Copy

1

2interface CommentFlagQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7}

8

Struttura della risposta di segnalazione commento

Copy

1

2

3interface CommentFlagResponse {

4 status: 'success' | 'failed'

5 /** Incluso in caso di errore. **/

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 /** Incluso in caso di errore. **/

8 reason?: string

9 /** Il commento è stato disapprovato (nascosto) a causa di troppe segnalazioni? **/

10 wasUnapproved?: boolean;

11}

12

Questo endpoint API fornisce la possibilità di rimuovere la segnalazione di un commento per uno specifico utente.

Note:

• Questa chiamata deve sempre essere effettuata nel contesto di un utente. L'utente può essere un FastComments.com User, SSO User, o Tenant User.
• Dopo che un commento è stato automaticamente non approvato (nascosto) - il commento può essere ri-approvato solo da un amministratore o moderatore. La rimozione della segnalazione (un-flag) non ri-approverà il commento.

Esempio cURL per la rimozione della segnalazione di un commento

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

Per la segnalazione anonima, dobbiamo specificare un anonUserId. Questo può essere un ID che rappresenta la sessione anonima, o un UUID casuale.

Esempio cURL per la rimozione della segnalazione di un commento anonimo

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

Struttura della richiesta per la rimozione della segnalazione di un commento

Copy

1

2interface CommentFlagQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7}

8

Struttura della risposta per la rimozione della segnalazione di un commento

Copy

1

2

3interface CommentUnFlagResponse {

4 status: 'success' | 'failed'

5 /** Incluso in caso di fallimento. **/

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 /** Incluso in caso di fallimento. **/

8 reason?: string

9}

10

Questo endpoint API consente di bloccare l'utente che ha scritto un determinato commento. Supporta il blocco per commenti scritti da FastComments.com Users, SSO Users, and Tenant Users.

Supporta un parametro nel body commentIdsToCheck per verificare se altri commenti potenzialmente visibili nel client debbano essere bloccati/sbloccati dopo l'esecuzione di questa azione.

Notes:

• Questa chiamata deve sempre essere effettuata nel contesto di un utente. L'utente può essere un FastComments.com User, SSO User, o Tenant User.
• Il userId nella richiesta è l'utente che sta eseguendo il blocco. Per esempio: User A vuole bloccare User B. Passa userId=User A e l'id del commento che User B ha scritto.
• Commenti completamente anonimi (no user id, no email) non possono essere bloccati e verrà restituito un errore.

Esempio cURL di blocco commento

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

Per il blocco anonimo, dobbiamo specificare un anonUserId. Questo può essere un ID che rappresenta la sessione anonima, o un UUID casuale. Questo ci permette di supportare il blocco dei commenti anche se un utente non è autenticato recuperando i commenti con lo stesso anonUserId.

Esempio cURL di blocco commento anonimo

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

Struttura richiesta blocco commento

Copy

1

2interface CommentBlockQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7 commentIdsToCheck?: string[]

8}

9

Struttura risposta blocco commento

Copy

1

2

3interface CommentBlockResponse {

4 status: 'success' | 'failed'

5 /** Incluso in caso di fallimento. **/

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 /** Incluso in caso di fallimento. **/

8 reason?: string

9 /** Se commentIdsToCheck è definito, le voci in questa mappa con valore true sono anch'esse bloccate. **/

10 commentStatuses?: Record<string, boolean>;

11}

12

Questo endpoint API fornisce la possibilità di sbloccare un utente che ha scritto un determinato commento. Supporta lo sblocco di commenti scritti da FastComments.com Users, SSO Users, e Tenant Users.

Supporta un parametro body commentIdsToCheck per verificare se altri commenti potenzialmente visibili sul client dovrebbero essere bloccati/sbloccati dopo che questa azione è stata eseguita.

Note:

• Questa chiamata deve essere sempre effettuata nel contesto di un utente. L'utente può essere un FastComments.com User, SSO User, o Tenant User.
• Il userId nella richiesta è l'utente che sta effettuando lo sblocco. Per esempio: User A vuole sbloccare User B. Passa userId=User A e l'id del commento che User B ha scritto.
• I commenti completamente anonimi (nessun user id, nessuna email) non possono essere bloccati e verrà restituito un errore.

Esempio cURL Sblocco Commento

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

Esempio cURL Sblocco Commento Anonimo

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

Struttura Richiesta Sblocco Commento

Copy

1

2interface CommentUnBlockQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7 commentIdsToCheck?: string[]

8}

9

Struttura Risposta Sblocco Commento

Copy

1

2

3interface CommentUnBlockResponse {

4 status: 'success' | 'failed'

5 /** Incluso in caso di errore. **/

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 /** Incluso in caso di errore. **/

8 reason?: string

9 /** Se commentIdsToCheck è definito, le voci in questa mappa con valore true sono ancora bloccate. Se false, potresti voler rendere nuovamente visibili i commenti all'utente in modo che non debba aggiornare. **/

10 commentStatuses?: Record<string, boolean>;

11}

12

I singoli EmailTemplate possono essere recuperati tramite il loro corrispondente id (NON emailTemplateId).

Esempio cURL per EmailTemplate per ID

Copy

1

2curl --request GET \

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

4

Struttura della richiesta EmailTemplate per ID

Copy

1

2interface EmailTemplatesByIdRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Struttura della risposta EmailTemplate per ID

Copy

1

2interface EmailTemplateResponse {

3 status: 'success' | 'failed'

4 /** Incluso in caso di errore. **/

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

6 /** Incluso in caso di errore. **/

7 reason?: string

8 emailTemplate?: EmailTemplate | null

9}

10

Questa API utilizza la paginazione, fornita dal parametro di query page. Gli EmailTemplates vengono restituiti in pagine da 100, ordinati per createdAt e poi per id.

Esempio cURL per 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

Struttura della richiesta EmailTemplate

Copy

1

2interface EmailTemplatesRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** La pagina da recuperare, a partire da 0. **/

6 page: number

7}

8

Struttura della risposta EmailTemplate

Copy

1

2interface EmailTemplatesResponse {

3 status: 'success' | 'failed'

4 /** Incluso in caso di errore. **/

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

6 /** Incluso in caso di errore. **/

7 reason?: string

8 emailTemplates: EmailTemplate[]

9}

10

Questo endpoint API fornisce la possibilità di aggiornare un template email specificando solo l'id e gli attributi da aggiornare.

Nota che tutte le stesse validazioni per la creazione di un template si applicano anche qui, per esempio:

• Il template deve poter essere renderizzato. Questo viene controllato ad ogni aggiornamento.
• Non puoi avere template duplicati per lo stesso dominio (altrimenti uno verrebbe ignorato silenziosamente).

Esempio 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

Struttura richiesta PATCH EmailTemplate

Copy

1

2interface EmailTemplatePatchQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Struttura risposta PATCH EmailTemplate

Copy

1

2

3interface EmailTemplatePatchResponse {

4 status: 'success' | 'failed'

5 /** Incluso in caso di errore. **/

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 /** Incluso in caso di errore. **/

8 reason?: string

9 /** Il template email aggiornato. **/

10 emailTemplate?: EmailTemplate

11}

12

Questo endpoint API consente di creare modelli email.

Note:

• Non puoi avere più template con lo stesso emailTemplateId nello stesso dominio.
• Tuttavia puoi avere un template wildcard (domain = *) e un template specifico per dominio per lo stesso emailTemplateId.
• Specificare domain è rilevante solo se hai domini diversi, o vuoi usare template specifici per i test (domain impostato su localhost ecc).
• Se specifichi domain deve corrispondere a una DomainConfig. In caso di errore viene fornito un elenco di domini validi.
• La sintassi del template è EJS e viene renderizzata con un timeout di 500ms. Il P99 per il rendering è <5ms, quindi se raggiungi i 500ms qualcosa non va.
• Il tuo template deve essere renderizzato con i testData forniti per poter essere salvato. Gli errori di rendering vengono aggregati e riportati nella dashboard (presto disponibile via API).

I dati minimi richiesti per aggiungere un template sono i seguenti:

Esempio minimo di richiesta cURL POST per 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

Potresti voler avere template per sito, nel qual caso definisci domain:

Esempio di richiesta cURL POST per 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

Struttura della richiesta POST per EmailTemplate

Copy

1

2interface EmailTemplatePostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Struttura della risposta POST per EmailTemplate

Copy

1

2

3interface EmailTemplatePostResponse {

4 status: 'success' | 'failed'

5 /** Incluso in caso di errore. **/

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 /** Incluso in caso di errore. **/

8 reason?: string

9 /** Il template creato. **/

10 emailTemplate?: EmailTemplate

11}

12

Questo endpoint API fornisce la possibilità di visualizzare in anteprima i modelli di email.

Esempio minimo cURL di anteprima EmailTemplate POST

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

Struttura della richiesta POST EmailTemplate

Copy

1

2interface EmailTemplatePostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Struttura della risposta POST EmailTemplate

Copy

1

2

3interface EmailTemplatePostResponse {

4 status: 'success' | 'failed'

5 /** Incluso in caso di fallimento. **/

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

7 /** Incluso in caso di fallimento. **/

8 reason?: string

9 /** L'HTML renderizzato in caso di successo. **/

10 html?: string

11}

12

Questa route consente la rimozione di un singolo EmailTemplate tramite id.

Esempio cURL di rimozione EmailTemplate

Copy

1

2curl --request DELETE \

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

4

Struttura della richiesta di rimozione EmailTemplate

Copy

1

2interface EmailTemplateRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Struttura della risposta di rimozione EmailTemplate

Copy

1

2interface EmailTemplateDeleteResponse {

3 status: 'success' | 'failed'

4 /** Incluso in caso di errore. **/

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

6 /** Incluso in caso di errore. **/

7 reason?: string

8}

9

Recupera i post in un feed, dal più recente. La paginazione è basata su cursore: passa l'_id dell'ultimo post ricevuto come afterId per ottenere la pagina successiva.

Costa un credito per ogni dieci post restituiti, con un minimo di un credito.

Esempio cURL 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

Struttura della Richiesta FeedPost

Copy

1

2interface FeedPostsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Return posts after this post id. Omit for the first page. **/

6 afterId?: string

7 /** Defaults to 10. Maximum 1000. **/

8 limit?: number

9 /** Only return posts with these tags. Repeat the parameter for more than one tag. **/

10 tags?: string[]

11}

12

Struttura della Risposta FeedPost

Copy

1

2interface FeedPostsResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

6 /** Included on failure. **/

7 reason?: string

8 feedPosts: FeedPost[]

9}

10

Questo endpoint crea un singolo FeedPost. Ogni post ha un autore, quindi fromUserId è obbligatorio e deve essere l'ID di un utente FastComments o SSO esistente nell'account.

Esempio cURL per Creare 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

Struttura della Richiesta di Creazione FeedPost

Copy

1

2interface FeedPostPostQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Invia il post ai feed aperti in un browser in questo momento. Predefinito a false. **/

6 isLive?: boolean

7 /** Esegui il post attraverso il motore anti-spam prima di salvarlo. Predefinito a false. **/

8 doSpamCheck?: boolean

9 /** Salta il controllo di contenuto ripetuto che viene eseguito come parte di doSpamCheck. Predefinito a false. **/

10 skipDupCheck?: boolean

11 /** Fino a 256 caratteri. Inviato agli ascoltatori live così un client può ignorare la propria trasmissione. **/

12 broadcastId?: string

13}

14

15interface FeedPostPostBody {

16 /** Obbligatorio. Un ID utente FastComments o SSO. **/

17 fromUserId: string

18 title?: string

19 /** HTML. Sanitizzato al salvataggio. **/

20 contentHTML?: string

21 /** Sovrascrive il nome visualizzato preso dall'utente. **/

22 fromUserDisplayName?: string

23 tags?: string[]

24 media?: FeedPostMediaItem[]

25 links?: FeedPostLink[]

26 meta?: Record<string, string>

27}

28

Struttura della Risposta di Creazione FeedPost

Copy

1

2interface FeedPostPostResponse {

3 status: 'success' | 'failed'

4 /** Incluso in caso di errore. **/

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 /** Incluso in caso di errore. **/

7 reason?: string

8 feedPost?: FeedPost; // Restituiamo il post completo creato in caso di successo.

9}

10

Questo endpoint aggiorna un singolo FeedPost. Invia solo i campi che desideri modificare.

Esempio cURL di aggiornamento 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