Segnalazioni | IntelligenceBox

Indirizzo del servizio auth

Usa AUTH_URL, l’URL del servizio di autenticazione della tua installazione. L’endpoint salva i ticket nel servizio cloud di supporto; l’indirizzo della Box e la chiave ricevuta all’apertura di un’app embed non sono utilizzabili per questa chiamata.

Inviare una segnalazione#

POSTAUTH_URL/api/v1/ticketsJWT / API key cloud

Crea un ticket aperto a nome dell’utente autenticato. Il pannello di supporto lo mostra nella coda esistente, filtrabile per sourceApp.

curl --request POST "$AUTH_URL/api/v1/tickets" \
  --header "Authorization: Bearer $REPORTS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "sourceApp": "customer-portal",
    "type": "BUG",
    "title": "Exported PDF does not open",
    "description": "Exporting from the documents page produces an unreadable PDF.",
    "context": { "externalId": "PORT-123", "appVersion": "2.4.0" }
  }'

Autenticazione#

Invia Authorization: Bearer <credenziale> con un JWT cloud firmato dal servizio auth oppure una chiave API cloud attiva e non scaduta. L’utente deve esistere e non essere bloccato. L’header x-api-key, i token di sessione better-auth e i JWT box-local non sono accettati da questo endpoint.

Puoi creare una chiave cloud usando il JWT dell’utente con POST /api/auth/api-key. Nell’esempio scade dopo 30 giorni. Conserva il valore key della risposta nel backend della tua applicazione e usalo come REPORTS_API_KEY.

Shell

curl --request POST "$AUTH_URL/api/auth/api-key" \
  --header "Authorization: Bearer $USER_JWT" \
  --header 'Content-Type: application/json' \
  --data '{"name":"customer-portal-reports","expiresIn":2592000}'

Le chiavi con permissions: null mantengono l’accesso completo. Una chiave con permessi limitati deve includere {"tickets":["create"]}. Le chiavi locali della Box e le chiavi boxe_ delle app embed non sono chiavi cloud.

A chi viene attribuito il ticket

Utente, email e azienda sono ricavati dalle credenziali e dal database. Una chiave condivisa crea ticket a nome del suo proprietario; per attribuirli ai singoli utenti servono le loro credenziali. Restano valide le regole di visibilità per segnalante, azienda, partner e staff.

Corpo della richiesta#

Invia JSON con Content-Type: application/json. Non serve l’envelope tRPC o SuperJSON. I campi non previsti vengono rifiutati: utente, azienda, stato, priorità e note del supporto non possono essere impostati dal chiamante.

Campo

sourceAppstringobbligatorio: Nome dell’app, da 1 a 60 caratteri. Inizia con una lettera ASCII o cifra; ammette anche spazi, punti, underscore e trattini. Diventa minuscolo, con spazi e underscore convertiti in trattini: Blue Desk → blue-desk. È una provenienza dichiarata, non un’identità verificata.
titlestringobbligatorio: Titolo da 3 a 200 caratteri, dopo la rimozione degli spazi iniziali e finali.
descriptionstringobbligatorio: Descrizione da 1 a 10.000 caratteri, dopo la rimozione degli spazi iniziali e finali.
type"BUG" | "SUGGESTION" | "QUESTION": BUG per un problema, SUGGESTION per una proposta, QUESTION per una domanda.Predefinito: BUG.
brandstring: Marchio associato alla segnalazione, fino a 100 caratteri.
screenshotstring: Data URL con prefisso data:image/, massimo 4.000.000 caratteri. Non inviare un URL remoto.
attachmentstring: Un documento come data URL con prefisso data:, massimo 8.000.000 caratteri.
attachmentNamestring: Nome del documento, fino a 255 caratteri. Le directory vengono rimosse; senza nome viene usato allegato. Ignorato quando attachment è assente.
attachmentMimestring: Tipo MIME del documento, fino a 255 caratteri. Ignorato quando attachment è assente.
uiLogsobject[]: Massimo 500 righe per array. Ogni riga contiene ts (max 40 caratteri), level (16), message (4.000) e facoltativamente src (120).
serverLogsobject[]: Massimo 500 righe per array. Ogni riga contiene ts (max 40 caratteri), level (16), message (4.000) e facoltativamente src (120).
contextobject: Metadati JSON, ad esempio versione dell’app, pagina, passi per riprodurre il problema o ID nel tuo sistema.

Dimensioni e limiti#

Il corpo HTTP completo può contenere al massimo 20.000.000 byte, anche senza Content-Length. Si applicano anche i limiti dei singoli campi. Eventuali quote e rate limit della chiave vengono rispettati; quota e ticket sono aggiornati nella stessa transazione. Un payload invalido o un salvataggio fallito non consumano quota.

Chiamata dal backend

L’integrazione è server-to-server. Conserva le chiavi nel backend: la policy CORS del servizio auth non abilita origini web arbitrarie.

Risposta#

Una richiesta riuscita restituisce 201 Created e Cache-Control: no-store. Conserva ticket.id nel sistema chiamante. Consultazione e conversazione restano nel pannello di supporto e nelle API auth.tickets.*.

201 Created

{
  "ticket": {
    "id": "cmexampleticket",
    "createdAt": "2026-09-07T10:00:00.000Z",
    "status": "OPEN",
    "sourceApp": "customer-portal"
  }
}

Invii ripetuti

Ogni POST riuscita crea un nuovo ticket. context.externalId è un metadato e non deduplica le richieste. Dopo un timeout verifica l’esito prima di ripetere l’invio.

Errori#

Gli errori restituiscono error.code e error.message. Gli errori di validazione includono error.issues, con percorso del campo e messaggio. Nessun dettaglio interno del database viene restituito.

400 Bad Request

{
  "error": {
    "code": "INVALID_JSON",
    "message": "Il corpo della richiesta non è JSON valido"
  }
}

400INVALID_JSON / VALIDATION_ERROR — corpo mancante, JSON malformato o campi non validi.
401UNAUTHORIZED — credenziali mancanti, scadute o non valide, chiave disabilitata oppure account non disponibile.
403FORBIDDEN — la chiave non consente tickets.create.
413PAYLOAD_TOO_LARGE — corpo oltre 20.000.000 byte.
415UNSUPPORTED_MEDIA_TYPE — usa Content-Type: application/json.
429RATE_LIMITED / QUOTA_EXCEEDED — limite o quota raggiunti. RETRY_REQUEST — chiave modificata o usata da una richiesta concorrente: nessun ticket creato; riprova con un breve backoff se la chiave è ancora valida.
500INTERNAL_ERROR — impossibile salvare la segnalazione.