Gestisci i reindirizzamenti di pagina con l'API Notiondesk

Un reindirizzamento di pagina indirizza i lettori che aprono un vecchio percorso nel tuo centro assistenza a un articolo o a una raccolta. L'API Notiondesk ti consente di elencare, creare, aggiornare ed eliminare i reindirizzamenti di pagina, in modo da poter importare centinaia di vecchi URL dopo una migrazione anziché aggiungerli uno per uno nella dashboard. I segnalibri, i link condivisi e i risultati dei motori di ricerca continuano a funzionare.

Per gestire i reindirizzamenti direttamente nella dashboard, consulta la sezione "Come gestire i reindirizzamenti di pagina nel centro assistenza" .

La creazione e l'aggiornamento dei reindirizzamenti richiedono un piano che includa i reindirizzamenti di pagina.

Elenco dei reindirizzamenti della pagina

L'elenco comprende tutte le lingue, dalla più recente alla meno recente. Include i reindirizzamenti creati dall'utente e quelli creati automaticamente da Notiondesk dopo una modifica dello slug.

curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/page-redirects?page_size=100" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

{
  "object": "list",
  "data": [
    {
      "id": "3f1c2a9e-8b7d-4c6e-9a5f-1e2d3c4b5a69",
      "locale": "en",
      "type": "article",
      "origin": "manual",
      "source_path": "/legacy/getting-started",
      "target_id": "1761580412",
      "target_title": "Getting started",
      "target_slug": "getting-started",
      "target_status": "published"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Nota: un reindirizzamento indirizza i lettori solo finché la destinazione è pubblicata. Un reindirizzamento a una bozza attende la pubblicazione della destinazione.

L'elenco contiene al massimo i 10.000 reindirizzamenti più recenti. Se la tua integrazione elimina i reindirizzamenti mentre li elenca, ricomincia dalla prima pagina: un'eliminazione sposta gli elementi successivi, quindi la pagina successiva può saltarne uno. Vedi Paginate e richieste API della versione Notiondesk .

Crea un reindirizzamento di pagina

Tutti i campi sono obbligatori:

curl -X POST "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/page-redirects" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f0d6b1e-create-getting-started" \
  -d '{"type": "article", "source_path": "/legacy/getting-started", "target_id": "1761580412", "locale": "en"}'

Il percorso risponde a 201 Created con il nuovo reindirizzamento, negli stessi campi dell'elenco.

• Un altro reindirizzamento utilizza già le risposte 409 e il messaggio specifica il percorso.

• Un target_id senza traduzione in locale risponde 404 not_found e il messaggio specifica l'ID.

Invia un Idempotency-Key con ogni creazione. Un nuovo tentativo con la stessa chiave e lo stesso corpo risponde con lo stesso 201 senza creare un secondo reindirizzamento. Vedi Gestione degli errori dell'API Notiondesk, dei limiti di frequenza e dei tentativi .

Aggiornare il reindirizzamento di una pagina

Invia solo i campi da modificare. Ogni campo che non invii manterrà il suo valore corrente.

I campi seguono le regole di creazione. Il percorso risponde a 200 OK con il reindirizzamento aggiornato.

Il reindirizzamento deve comunque puntare a una destinazione che esiste nel suo locale dopo la modifica. Per far puntare un reindirizzamento di un articolo a una raccolta, inviare type e target_id insieme.

Elimina un reindirizzamento di pagina

L'eliminazione è irreversibile, quindi il percorso necessita di due misure di sicurezza:

curl -X PATCH "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/page-redirects/3f1c2a9e-8b7d-4c6e-9a5f-1e2d3c4b5a69" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16" \
  -H "Content-Type: application/json" \
  -d '{"source_path": "/legacy/start"}'

curl -i -X DELETE "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/page-redirects/3f1c2a9e-8b7d-4c6e-9a5f-1e2d3c4b5a69" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16" \
  -H "Content-Type: application/json" \
  -d '{"confirm": true}'

• l'ambito admin;

• il corpo {"confirm": true}, con il valore booleano JSON true.

Il percorso risponde 204 No Content. I lettori che aprono il vecchio percorso non vengono più reindirizzati. Eliminando nuovamente lo stesso reindirizzamento si ottiene una risposta 404 not_found, a meno che non si riprovi con lo stesso Idempotency-Key.

L'ambito funziona solo su una chiave creata dal proprietario dell'area di lavoro o da un amministratore. Un editor può eliminare un reindirizzamento nella dashboard, ma non tramite una chiave API.admin

Importa i reindirizzamenti dopo una migrazione

Stai passando da un altro strumento per il centro assistenza? Associa ogni vecchio percorso al suo nuovo articolo, quindi crea un reindirizzamento per ogni riga. Questo script legge un file CSV con le colonne source_path,target_id,locale:

import { readFileSync } from "node:fs";
import { createHash } from "node:crypto";

const siteId = "c74781f6-1aea-4e17-ab23-bbb8b4d174b6";
const rows = readFileSync("redirects.csv", "utf8").trim().split(/\r?\n/).slice(1);

for (const row of rows) {
  const [source_path, target_id, locale] = row.split(",");
  const idempotencyKey = createHash("sha256").update(`${source_path}|${target_id}|${locale}`).digest("hex");

  const response = await fetch(`https://api.notiondesk.so/sites/${siteId}/page-redirects`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.NOTIONDESK_API_KEY}`,
      "nd-version": "2026-10-16",
      "Content-Type": "application/json",
      "Idempotency-Key": idempotencyKey,
    },
    body: JSON.stringify({ type: "article", source_path, target_id, locale }),
  });

  if (response.status === 429) {
    const seconds = Number(response.headers.get("Retry-After")) || 5;
    console.log(`Rate limited, waiting ${seconds}s`);
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
    rows.push(row);
    continue;
  }

  const result = await response.json();
  console.log(response.status, source_path, response.ok ? result.id : result.code);
}

• La chiave viene derivata dalla riga, quindi eseguire lo script due volte non crea nulla due volte. Una riga che viene corretta riceve una nuova chiave.

• Un percorso che ha già un reindirizzamento registra conflict_error. Aggiornalo invece, oppure lascialo così com'è.

• Le scritture sono limitate a 20 richieste al minuto per chiave, quindi 500 reindirizzamenti richiedono circa 25 minuti. Lo script attende quando raggiunge il limite di richieste, quindi riprova a eseguire la riga.

• Utilizzare una chiave con gli ambiti read e write soltanto.

Errori

Consultare la sezione "Errori API, limiti di frequenza e tentativi" dell'handle Notiondesk per informazioni sull'intestazione dell'errore e sugli altri codici.

Domande frequenti

Cosa succederà dopo?

• Automatizza le attività comuni del centro assistenza con l'API Notiondesk

• Leggi articoli, raccolte e voci del registro delle modifiche con l'API Notiondesk

• Gestire gli errori dell'API Notiondesk, i limiti di frequenza e i tentativi di ripetizione.