API per agenti e servizi esterni

Autenticazione

Apri Impostazioni → Team e accesso → Agenti IA per creare un agente IA gestito oppure Impostazioni → API e agenti per creare una chiave con ambito per un utente esistente. Copia il token una sola volta, conservalo fuori dal repository sorgente e invia richieste solo tramite HTTPS.

L’API valuta sia gli ambiti selezionati del token sia le autorizzazioni dell’utente proprietario. Un token non può leggere o modificare ticket a cui il proprietario non è autorizzato ad accedere.

Avvia ogni sessione di integrazione

GET index.php?page=api&action=agent-docs: carica istruzioni e contratti di richiesta aggiornati e abbinati alla versione.
GET index.php?page=api&action=agent-me: verifica identità, autorizzazioni e ambiti del token.

Non usare il token nella pagina di accesso del browser. Le richieste degli agenti usano il percorso canonico index.php?page=api&action=agent-*.

Endpoint comuni

GET agent-list-tickets: elenca e cerca i ticket visibili.
GET agent-get-ticket: carica un ticket visibile e la relativa cronologia.
POST agent-create-ticket: crea un ticket.
POST agent-add-update: aggiunge un commento pubblico o una nota interna senza tempo.
POST agent-add-work-entry: aggiunge in modo atomico un commento collegato e una registrazione oraria.
POST agent-plan-work-log e agent-apply-work-log-plan: visualizza e conferma registri di lavoro strutturati.
POST agent-update-status: modifica lo stato di un ticket.
POST agent-log-time: aggiunge una registrazione oraria indipendente.

L’elenco completo degli endpoint, dei campi e dei vincoli correnti proviene da agent-docs; non copiare uno schema di richiesta obsoleto in un’integrazione.

Esempio di richiesta

FOXDESK_BASE_URL=https://helpdesk.example.com
FOXDESK_API_TOKEN=fdx_replace_with_token_from_settings

curl -fsS -X POST \
  "$FOXDESK_BASE_URL/index.php?page=api&action=agent-add-update" \
  -H "Authorization: Bearer $FOXDESK_API_TOKEN" \
  -H "Idempotency-Key: comment-ticket-542-20260729-01" \
  -H "Content-Type: application/json" \
  --data '{
    "ticket_id": 542,
    "content": "The nightly backup completed successfully.",
    "is_internal": true
  }'

Usa una Idempotency-Key univoca per ogni richiesta di scrittura. Inizia con ambiti di sola lettura, aggiungi ambiti di scrittura solo per il flusso previsto e usa il flusso pianifica/applica quando un utente richiede un registro di lavoro strutturato.