Gestiona las redirecciones de página con la API Notiondesk

Una redirección de página dirige a los lectores que acceden a una ruta antigua en tu centro de ayuda a un artículo o una colección. La API te permite listar, crear, actualizar y eliminar redirecciones de página, de modo que puedes importar cientos de URL antiguas tras una migración en lugar de añadirlas una a una en el panel de control. Los marcadores, los enlaces compartidos y los resultados de los motores de búsqueda siguen funcionando.

Para gestionar las redirecciones desde el panel de control, consulta la sección «Cómo gestionar las redirecciones de página» en tu centro de ayuda .

La creación y actualización de redirecciones requiere un plan que incluya redirecciones de página.

Lista de redirecciones de página

La lista abarca todos los idiomas, del más reciente al más antiguo. Incluye las redirecciones que usted crea y las que Notiondesk crea automáticamente después de un cambio de 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: Una redirección solo envía a los lectores mientras el contenido de destino esté publicado. Una redirección a un borrador espera hasta que se publique el contenido de destino.

La lista muestra como máximo las 10 000 redirecciones más recientes. Si su integración elimina redirecciones mientras las muestra, vuelva a empezar desde la primera página: una eliminación desplaza los elementos siguientes, por lo que la siguiente página puede saltarse uno. Consulte las solicitudes de API de paginación y versión Notiondesk .

Crear una redirección de página

Todos los campos son obligatorios:

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"}'

La ruta responde a 201 Created con la nueva redirección, en los mismos campos que la lista.

• Una source_path otra redirección ya utiliza respuestas 409 conflict_error, y el mensaje nombra la ruta.

• Un target_id sin traducción en locale responde 404 not_found, y el mensaje nombra el id.

Envía un Idempotency-Key con cada creación. Un reintento con la misma clave y cuerpo responde con el mismo 201 sin crear una segunda redirección. Consulta Manejar errores de API, límites de velocidad y reintentos Notiondesk .

Actualizar una redirección de página

Envía únicamente los campos que deseas modificar. Los campos que omitas conservarán su valor actual.

Los campos siguen las reglas de creación. La ruta responde a 200 OK con la redirección actualizada.

La redirección debe seguir apuntando a un destino que exista en su locale después del cambio. Para que una redirección de artículo apunte a una colección, envíe type y target_id juntos.

Eliminar una redirección de página

La eliminación es irreversible, por lo que la ruta necesita dos medidas de seguridad:

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}'

• el ámbito admin;

• el cuerpo {"confirm": true}, con el booleano JSON true.

La ruta responde 204 No Content. Los lectores que abren la ruta anterior dejan de ser redirigidos. Eliminar la misma redirección de nuevo responde 404 not_found, a menos que se vuelva a intentar con el mismo Idempotency-Key.

El alcance solo funciona con una clave creada por el propietario o administrador del espacio de trabajo. Un editor puede eliminar una redirección en el panel de control, pero no con una clave API.admin

Importar redirecciones después de una migración

¿Viajas desde otra herramienta del centro de ayuda? Asigna cada ruta antigua a su nuevo artículo y luego crea una redirección por fila. Este script lee un archivo CSV con las columnas 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 clave se deriva de la fila, por lo que ejecutar el script dos veces no duplica la funcionalidad. Cada fila que se corrige obtiene una clave nueva.

• Una ruta que ya tiene un registro de redirección conflict_error. Actualícela o déjela como está.

• Las escrituras están limitadas a 20 solicitudes por minuto por clave, por lo que 500 redirecciones tardan aproximadamente 25 minutos. El script espera cuando se alcanza el límite de solicitudes y luego vuelve a intentar la fila.

• Utilice únicamente una clave con los ámbitos read y write.

Errores

Consulte Handle Notiondesk Errores de API, límites de velocidad y reintentos para obtener el envoltorio de error y los demás códigos.

Preguntas frecuentes

¿Qué sigue?

• Automatice las tareas comunes del centro de ayuda con la API Notiondesk.

• Lee artículos, colecciones y entradas del registro de cambios con la API Notiondesk

• Gestionar errores de la API Notiondesk, límites de velocidad y reintentos.