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

La API Notiondesk lee todo lo que publica tu centro de ayuda: cada artículo y colección en cualquier idioma, con su contenido en formato Markdown, su estado de publicación y su estado de sincronización, además de las entradas del registro de cambios publicadas. Úsala para hacer copias de seguridad de tu centro de ayuda, enviar tu contenido a otra herramienta o comprobar qué artículos no se sincronizaron correctamente.

La API lee el contenido, pero nunca lo escribe. Tus artículos y colecciones permanecen en Notion: para modificar alguno, edítalo en Notion y activa la sincronización .

En la API Notiondesk, una colección se denomina categoría .

Elige el idioma

Cada ruta en esta página acepta un parámetro de consulta opcional locale, como ?locale=fr. Sin él, la respuesta utiliza el idioma predeterminado del centro de ayuda. En las rutas de lista, locale debe ser uno de los idiomas que admite el centro de ayuda: el supported_locales del centro de ayuda . Consulta la sección «Admitir varios idiomas en tu centro de ayuda» para agregar idiomas.

Lista de artículos

La lista incluye todos los artículos en todos los estados, borradores y artículos archivados también, en el orden en que fueron creados. Navegue por ella con page_size y cursor, como se describe en Solicitudes de API de paginación y versión Notiondesk .

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

{
  "object": "list",
  "data": [
    {
      "id": "1761580412",
      "title": "Connect your Notion workspace",
      "slug": "connect-your-notion-workspace",
      "status": "published",
      "categories": [
        {"id": "910000002", "name": "Connecting Notion", "slug": "connecting-notion", "locale": "en", "status": "published"}
      ],
      "tags": [{"name": "Setup", "slug": "setup"}],
      "locales_count": 2,
      "updated_at": "2026-10-18T14:39:03+00:00",
      "published_at": "2026-10-05T04:39:04+00:00",
      "locale": "en",
      "reading_time": 3,
      "views_count": 42,
      "reactions_percent": {"smiley": 50, "neutral_face": 25, "disappointed": 25},
      "source_notion_page_id": "3d5001d0-2470-8122-a1b2-c3d4e5f60789",
      "notion_article_page_url": "https://www.notion.so/3d5001d024708122a1b2c3d4e5f60789",
      "sync_in_progress": false,
      "sync_timeout": false,
      "sync_failed": false,
      "sync_error_code": null,
      "auto_translated": false
    }
  ],
  "has_more": true,
  "next_cursor": "OPAQUE_CURSOR"
}

Nota: Filtra los resultados en tu código para encontrar todos los artículos cuya última sincronización falló, luego corrígelo en Notion y vuelve a sincronizarlo .sync_failed: true

Lee un artículo en formato Markdown.

curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/articles/1761580412?locale=en" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

{
  "id": "1761580412",
  "type": "article",
  "title": "Connect your Notion workspace",
  "slug": "connect-your-notion-workspace",
  "text": "# Connect your Notion workspace\n\nOpen **Settings**, then **Notion**...",
  "url": "https://help.example.com/en/articles/connect-your-notion-workspace",
  "locale": "en",
  "last_updated": "2026-10-18T14:39:03+00:00",
  "category": {"id": "910000002", "title": "Connecting Notion", "slug": "connecting-notion"},
  "tags": ["setup"],
  "truncated": false,
  "author": {"name": "Ada Lovelace"},
  "status": "published",
  "content_available": true,
  "sync_in_progress": false,
  "sync_timeout": false,
  "sync_failed": false,
  "sync_error_code": null
}

Cada estado es legible, por lo que puede leer un borrador antes de publicarlo. Un artículo sin traducción en el campo locale solicitado devuelve el error 404 not_found.

Listar colecciones

Cada elemento es una colección en el idioma solicitado, en el orden en que se crearon las colecciones:

Reconstruye tu árbol de colección con tres campos:

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

{
  "id": "910000001",
  "name": "Getting Started",
  "slug": "getting-started",
  "updated_at": "2026-10-18T14:39:12+00:00",
  "locale": "en",
  "is_parent": true,
  "source_notion_page_id": "5d5001d0-2470-8122-a1b2-c3d4e5f60789",
  "notion_category_page_url": "https://www.notion.so/5d5001d024708122a1b2c3d4e5f60789",
  "sync_in_progress": false,
  "sync_timeout": false,
  "sync_failed": false,
  "sync_error_code": null,
  "parent_ids": [],
  "children_ids": ["910000002"],
  "locales_count": 2,
  "status": "published",
  "auto_translated": false
}

La lista no incluye el número de artículos. Para contar los artículos de una colección, enumérelos y agrúpelos por categories. Aprenda cómo las colecciones organizan su centro de ayuda en Usar colecciones para organizar sus artículos .

Lee una colección

La respuesta tiene la misma forma que un artículo: type es category, title, slug, url, status, los campos de sincronización y text con el propio contenido de la colección como markdown, vacío cuando no tiene ninguno.

Lista de entradas del registro de cambios

El registro de cambios enumera los artículos publicados que se encuentran en tus colecciones de registros de cambios, del más reciente al más antiguo. Configúralo en Configuración de registros de cambios en tu centro de ayuda .

curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/categories/910000001?locale=en" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

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

{
  "object": "list",
  "data": [
    {
      "id": "article:1761497350",
      "title": "Multilingual sync is now available",
      "slug": "multilingual-sync-is-now-available",
      "text": "Help centers on the Enterprise plan can now sync every configured locale in a single run instead of one language at a time.",
      "published_at": "2026-10-13T09:12:44+00:00",
      "last_updated": "2026-10-18T14:39:03+00:00",
      "tags": [],
      "url": "https://help.example.com/en/changelogs",
      "locale": "en"
    }
  ],
  "has_more": true,
  "next_cursor": "OPAQUE_CURSOR"
}

Es bueno saberlo:

• Una entrada solo aparece cuando su registro de cambios se publica en el idioma solicitado.

• En un centro de ayuda que utiliza cuentas de invitado, la lista muestra solo las entradas que todos los lectores pueden ver.

• La lista llega como máximo a las 1000 entradas más recientes. Más allá de eso, has_more es false incluso cuando existen entradas más antiguas.

• En raras ocasiones, durante un problema temporal del servicio, la lista puede omitir o repetir alguna entrada. Vuelva a consultarla más tarde para obtener la lista completa.

Errores

Cada ruta también puede responder a invalid_version, authentication_error, rate_limited y internal_error. Consulte Manejo de errores de API, límites de velocidad y reintentos de Notiondesk .

Preguntas frecuentes

¿Qué sigue?

• Trigger Notion se sincroniza con la API Notiondesk

• Gestiona idiomas y traducción automática con la API Notiondesk

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