Centro assistenza

Gestisci gli articoli del centro assistenza di un progetto e le loro categorie. Richiede che il centro assistenza sia attivo per il progetto — quando è disattivato, tutti gli endpoint qui sotto restituiscono 404.

Il corpo degli articoli è Markdown, non HTML. Il portale li mostra tramite un visualizzatore che non valuta mai HTML grezzo, quindi qualsiasi HTML inviato viene mostrato ai lettori come testo letterale.

Gli articoli nascono sempre come bozze — pubblicare è un PATCH separato, così nulla raggiunge il portale per sbaglio. Creare un articolo richiede l’accesso in scrittura di un piano a pagamento, come ogni altro metodo che modifica dati qui.

Elencare gli articoli

curl "https://api.supdesk.app/v1/articles?status=published&limit=10" \
  -H "Authorization: Bearer sd_live_..."

{
  "data": [
    {
      "id": "8f7a...",
      "title": "Come reimposto la password?",
      "slug": "come-reimposto-la-password",
      "body": "Apri **Impostazioni**, poi scegli *Reimposta password*.",
      "excerpt": "Apri Impostazioni, poi scegli Reimposta password.",
      "status": "published",
      "category_id": "3c2b...",
      "published_at": "2026-07-01T09:12:00Z",
      "helpful_count": 12,
      "not_helpful_count": 1,
      "created_at": "2026-06-28T14:03:00Z",
      "updated_at": "2026-07-01T09:12:00Z"
    }
  ],
  "pagination": { "limit": 10, "offset": 0, "has_more": false }
}

Senza filtro restituisce anche bozze e articoli archiviati, con la modifica più recente per prima. Usa status=published per ciò che i clienti vedono davvero.

Cercare articoli

curl "https://api.supdesk.app/v1/articles/search?q=reimposta+password&limit=5" \
  -H "Authorization: Bearer sd_live_..."

{
  "data": [
    {
      "id": "8f7a...",
      "title": "Come reimposto la password?",
      "slug": "come-reimposto-la-password",
      "category_slug": "per-iniziare",
      "category_name": "Per iniziare",
      "snippet": "Apri Impostazioni, poi scegli Reimposta password.",
      "rank": 0.6079
    }
  ]
}

Ricerca full-text solo sugli articoli pubblicati, ordinata per rilevanza, con uno stralcio in testo semplice attorno alla corrispondenza. I titoli pesano più dei riassunti, e i riassunti più del corpo. Una query vuota o non interpretabile restituisce un elenco vuoto invece di un errore.

Ottenere un articolo

curl "https://api.supdesk.app/v1/articles/8f7a..." \
  -H "Authorization: Bearer sd_live_..."

Restituisce un singolo articolo nella stessa forma dell’elenco, oppure 404 quando l’id è sconosciuto nel tuo progetto.

Creare un articolo

curl -X POST https://api.supdesk.app/v1/articles \
  -H "Authorization: Bearer sd_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Come reimposto la password?",
    "body": "Apri **Impostazioni**, poi scegli *Reimposta password*.",
    "category_id": "3c2b..."
  }'

{
  "data": {
    "id": "8f7a...",
    "title": "Come reimposto la password?",
    "slug": "come-reimposto-la-password",
    "body": "Apri **Impostazioni**, poi scegli *Reimposta password*.",
    "excerpt": "Apri Impostazioni, poi scegli Reimposta password.",
    "status": "draft",
    "category_id": "3c2b...",
    "published_at": null,
    "helpful_count": 0,
    "not_helpful_count": 0,
    "created_at": "2026-07-01T09:12:00Z",
    "updated_at": "2026-07-01T09:12:00Z"
  }
}

Restituisce 201. Omettendo slug ne viene derivato uno dal titolo, con suffisso -2, -3… se quell’indirizzo è occupato. Omettendo excerpt viene derivato dal corpo.

Il tuo piano limita quanti articoli un progetto può tenere — Free 5, Pro 50, Team illimitati. Oltre il limite questo restituisce limit_reached (429). Gli articoli archiviati non contano, quindi archiviarne uno libera un posto.

Aggiornare un articolo

curl -X PATCH https://api.supdesk.app/v1/articles/8f7a... \
  -H "Authorization: Bearer sd_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "published" }'

Vengono scritti solo i campi che invii, quindi un PATCH non svuota mai qualcosa che hai tralasciato. Impostare status a published registra published_at la prima volta e poi lo conserva — correggere un refuso non fa sembrare nuovo un articolo vecchio. Impostarlo a archived ritira l’articolo senza eliminarlo.

Ripristinare un articolo dall’archivio ricontrolla il limite del piano, e può restituire limit_reached.

Eliminare un articolo

curl -X DELETE https://api.supdesk.app/v1/articles/8f7a... \
  -H "Authorization: Bearer sd_live_..."

Elimina definitivamente l’articolo e il feedback dei suoi lettori, e restituisce 204. Per ritirare un articolo conservandolo, imposta invece il suo stato su archived.

Categorie

curl -X POST https://api.supdesk.app/v1/article-categories \
  -H "Authorization: Bearer sd_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Per iniziare", "sort_order": 1 }'

{
  "data": {
    "id": "3c2b...",
    "name": "Per iniziare",
    "slug": "per-iniziare",
    "description": null,
    "sort_order": 1,
    "created_at": "2026-07-01T09:12:00Z"
  }
}

Le categorie sono elencate per sort_order, poi per nome. Gli slug sono derivati dal nome nello stesso modo in cui gli slug degli articoli sono derivati dal titolo.

Eliminare una categoria restituisce 204 e non elimina i suoi articoli — restano senza categoria e continuano a essere raggiungibili dalla ricerca e dalla pagina iniziale del centro assistenza.

Errori

Oltre ai codici standard: