Управление перенаправлениями страниц с помощью API Notiondesk

Перенаправление страницы отправляет читателей, открывших старый путь в вашем справочном центре, на статью или подборку. API Notiondesk позволяет просматривать, создавать, обновлять и удалять перенаправления страниц, так что вы можете импортировать сотни старых URL-адресов после миграции, вместо того чтобы добавлять их по одному на панели управления. Закладки, общие ссылки и результаты поиска остаются работоспособными.

Чтобы управлять перенаправлениями на панели управления, см. раздел «Как управлять перенаправлениями страниц» в справочном центре .

Для создания и обновления перенаправлений требуется тарифный план, включающий перенаправления страниц.

Список перенаправлений страниц

Список охватывает все языки, начиная с самых новых. Он включает в себя как созданные вами перенаправления, так и те, которые Notiondesk создает автоматически после изменения слага.

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
}

Примечание: Перенаправление отправляет читателей только в том случае, если целевой ресурс опубликован. Перенаправление на черновик ожидает публикации целевого ресурса.

Список содержит максимум 10 000 самых новых перенаправлений. Если ваша интеграция удаляет перенаправления во время их отображения, начните заново с первой страницы: удаление сдвигает следующие элементы, поэтому на следующей странице можно пропустить один из них. См. раздел «Пагинация» и запросы API версии Notiondesk .

Создать перенаправление страницы

Все поля обязательны для заполнения:

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

Маршрут отвечает 201 Created новым перенаправлением, используя те же поля, что и список.

• В сообщении source_path другой редирект уже использует ответ 409 conflict_error, и в сообщении указан путь.

• Сообщение target_id без перевода в locale отвечает кодом 404 not_found, и в сообщении указывается идентификатор.

Отправляйте Idempotency-Key при каждом создании. Повторная попытка с тем же ключом и телом запроса возвращает тот же 201 без создания второго перенаправления. См. раздел «Обработка ошибок API Notiondesk, ограничений скорости и повторных попыток» .

Обновить перенаправление страницы

Отправлять только поля, которые нужно изменить. Для каждого поля, которое вы пропустите, значение останется прежним.

Поля соответствуют правилам создания. Маршрут отвечает 200 OK с обновленным перенаправлением.

Перенаправление должно по-прежнему указывать на целевой объект, который существует в его locale после внесения изменений. Чтобы перенаправить статью на коллекцию, отправьте type и target_id вместе.

Удалить перенаправление страницы

Удаление необратимо, поэтому маршруту необходимы две меры предосторожности:

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

• область действия admin;

• Тело запроса {"confirm": true} содержит логическое значение JSON true.

Маршрут отвечает 204 No Content. Пользователи, открывающие старый путь, перестают получать перенаправление. Повторное удаление того же перенаправления приводит к ошибке 404 not_found, если только вы не повторите попытку с тем же Idempotency-Key.

Данная область действия распространяется только на ключ, созданный владельцем рабочей области или администратором. Редактор может удалить перенаправление на панели управления, но не с помощью ключа API.admin

Импорт перенаправлений после миграции

Переходите с другого инструмента для создания справочных центров? Сопоставьте каждый старый путь с новой статьей, а затем создайте одно перенаправление для каждой строки. Этот скрипт считывает CSV-файл со столбцами 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);
}

• Ключ определяется по строке, поэтому двукратное выполнение скрипта ничего не создаст дважды. Исправленная строка получит новый ключ.

• Путь, для которого уже существует перенаправление, записывает в журнал conflict_error. Обновите его или оставьте как есть.

• Количество запросов на запись ограничено 20 в минуту на каждый ключ, поэтому 500 перенаправлений займут около 25 минут. Скрипт ожидает, когда будет достигнуто ограничение по количеству запросов, а затем повторяет попытку обработки строки.

• Используйте ключ только с областями действия read и write.

Ошибки

См. раздел «Обработка ошибок API Notiondesk, ограничений скорости и повторных попыток» для получения информации о коде ошибки и других кодах.

Часто задаваемые вопросы

Что дальше?

• Автоматизируйте стандартные задачи справочного центра с помощью API Notiondesk

• Читайте статьи, подборки и записи об изменениях с помощью API Notiondesk

• Обработка ошибок API Notiondesk, ограничений скорости и повторных попыток.