Gerencie redirecionamentos de página com a API Notiondesk

Um redirecionamento de página envia os leitores que acessam um caminho antigo na sua central de ajuda para um artigo ou uma coleção. A API Notiondesk permite listar, criar, atualizar e excluir redirecionamentos de página, possibilitando a importação de centenas de URLs antigas após uma migração, em vez de adicioná-las uma a uma no painel de controle. Os favoritos, links compartilhados e resultados de mecanismos de busca continuam funcionando.

Para gerenciar redirecionamentos no painel de controle, consulte Como gerenciar redirecionamentos de página na sua central de ajuda .

Criar e atualizar redirecionamentos exige um plano que inclua redirecionamentos de página.

Redirecionamentos da página de lista

A lista abrange todos os idiomas, do mais recente para o mais antigo. Ela inclui os redirecionamentos que você cria e aqueles que o Notiondesk cria automaticamente após uma alteração 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
}

Observação: um redirecionamento envia conteúdo apenas para os leitores enquanto o conteúdo de destino estiver publicado. Um redirecionamento para um rascunho aguarda até que você publique o conteúdo de destino.

A lista atinge, no máximo, os 10.000 redirecionamentos mais recentes. Se a sua integração excluir redirecionamentos enquanto os lista, recomece a partir da primeira página em seguida: uma exclusão desloca os itens seguintes, permitindo que a próxima página pule um. Consulte Paginate e solicitações de API de versão Notiondesk .

Criar um redirecionamento de página

Todos os campos são obrigatórios:

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

A rota responde 201 Created com o novo redirecionamento, nos mesmos campos da lista.

• Um redirecionamento source_path já usa respostas 409 conflict_error, e a mensagem nomeia o caminho.

• Um target_id sem tradução em locale responde 404 not_found, e a mensagem nomeia o id.

Envie um Idempotency-Key com cada criação. Uma nova tentativa com a mesma chave e corpo retorna o mesmo 201 sem criar um segundo redirecionamento. Consulte Lidar com erros de API Notiondesk, limites de taxa e novas tentativas .

Atualizar redirecionamento de página

Envie apenas os campos que devem ser alterados. Todos os campos que você omitir manterão seus valores atuais.

Os campos seguem as regras de criação. A rota responde com 200 OK com o redirecionamento atualizado.

O redirecionamento ainda deve apontar para um destino que exista em seu locale após a alteração. Para direcionar um redirecionamento de artigo para uma coleção, envie type e target_id juntos.

Excluir redirecionamento de página

A exclusão é irreversível, portanto a rota precisa de duas salvaguardas:

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

• o escopo admin;

• o corpo {"confirm": true}, com o booleano JSON true.

A rota responde com 204 No Content. Os leitores que abrirem o caminho antigo param de ser redirecionados. Excluir o mesmo redirecionamento novamente retorna 404 not_found, a menos que você tente novamente com o mesmo Idempotency-Key.

O escopo funciona apenas com uma chave criada pelo proprietário do espaço de trabalho ou pelo administrador. Um editor pode excluir um redirecionamento no painel, mas não com uma chave de API.admin

Redirecionamentos de importação após uma migração

Migrando de outra ferramenta de central de ajuda? Mapeie cada caminho antigo para o seu novo artigo e, em seguida, crie um redirecionamento por linha. Este script lê um arquivo CSV com as colunas 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);
}

• A chave é derivada da linha, portanto, executar o script duas vezes não cria nada duas vezes. Uma linha que você corrige recebe uma nova chave.

• Um caminho que já possui um redirecionamento registra conflict_error. Atualize-o ou deixe-o como está.

• As gravações são limitadas a 20 solicitações por minuto por chave, portanto, 500 redirecionamentos levam cerca de 25 minutos. O script aguarda quando atinge o limite de taxa e, em seguida, tenta novamente a linha.

• Use uma chave somente com os escopos read e write.

Erros

Consulte a seção sobre erros da API Handle Notiondesk, limites de taxa e novas tentativas para obter informações sobre o envelope do erro e os demais códigos.

Perguntas frequentes

O que vem a seguir?

• Automatize tarefas comuns da central de ajuda com a API Notiondesk

• Leia artigos, coleções e entradas do changelog com a API Notiondesk

• Lidar com erros da API Notiondesk, limites de taxa e novas tentativas.