Solicitudes de API de paginación y versión Notiondesk

Cada lista de API Notiondesk utiliza la misma paginación de cursor, y cada solicitud puede especificar la versión de la API con la que se desarrolló la integración mediante el encabezado nd-version. Este artículo explica cómo funciona la paginación de la API Notiondesk, cómo leer cada página de una lista, cómo funciona el control de versiones de la API y las reglas de nomenclatura para campos y parámetros.

Cómo funciona la paginación de la API Notiondesk

Cada ruta de lista responde al mismo sobre:

{
  "object": "list",
  "data": [],
  "has_more": false,
  "next_cursor": null
}

Controla la página con dos parámetros de consulta:

Las listas no incluyen números de página ni recuento total.

Lee todas las páginas de una lista.

Repita la solicitud con cursor establecido al next_cursor de la respuesta anterior hasta que has_more sea false.

La primera página:

La página siguiente, con NEXT_CURSOR reemplazado por el next_cursor codificado en URL de la primera página:

El mismo bucle en JavaScript:

Y en Python:

Reglas del cursor

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

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

async function listAll(path) {
  const items = [];
  let cursor = null;

  do {
    const url = new URL(`https://api.notiondesk.so${path}`);
    url.searchParams.set("page_size", "100");
    if (cursor) {
      url.searchParams.set("cursor", cursor);
    }

    const response = await fetch(url, {
      headers: {
        Authorization: `Bearer ${process.env.NOTIONDESK_API_KEY}`,
        "nd-version": "2026-10-16",
      },
    });
    const page = await response.json();

    items.push(...page.data);
    cursor = page.has_more ? page.next_cursor : null;
  } while (cursor);

  return items;
}

const articles = await listAll("/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/articles");

import os
import requests

def list_all(path):
    items, cursor = [], None
    while True:
        params = {"page_size": 100}
        if cursor:
            params["cursor"] = cursor
        page = requests.get(
            f"https://api.notiondesk.so{path}",
            params=params,
            headers={
                "Authorization": f"Bearer {os.environ['NOTIONDESK_API_KEY']}",
                "nd-version": "2026-10-16",
            },
        ).json()
        items.extend(page["data"])
        if not page["has_more"]:
            return items
        cursor = page["next_cursor"]

• El cursor es opaco. No lo analice ni cree uno propio. Devuélvalo exactamente como lo recibió.

• Puedes cambiar page_size entre páginas. La siguiente página comienza donde terminó la anterior.

• El cursor mantiene una posición, no una instantánea. Si se agrega o elimina un elemento mientras se muestra la página, los elementos que aparecen después pueden desplazarse, por lo que una página puede repetir u omitir un elemento. Si la integración elimina elementos mientras los muestra, deberá comenzar de nuevo desde la primera página.

• Algunas listas se detienen antes de tiempo. La lista de cambios alcanza como máximo las 1000 entradas más recientes. Las redirecciones de página y los comentarios alcanzan como máximo las 10 000 más recientes. Superado ese límite, has_more se convierte en false.

• Algunas listas nunca se paginan. Los temas y las integraciones siempre devuelven todo en una sola respuesta, con has_more: false.

Un cursor mal formado, o uno que apunta más allá del final de la lista, responde 400 validation_error.

Versión de su integración de API Notiondesk

Envía el encabezado opcional nd-version para fijar la versión del contrato con la que se escribió tu integración:

nd-version: 2026-10-16

• Sin la cabecera, la solicitud utiliza la versión actual.

• Cada respuesta indica la versión que la respondió en su propio encabezado nd-version.

• Un valor desconocido responde 400 invalid_version.

Las nuevas rutas, los nuevos parámetros opcionales y los nuevos campos de respuesta se implementan sin necesidad de una nueva versión. Tu integración debe ignorar los campos que no reconoce, por lo que un nuevo campo nunca la interrumpirá.

Nota: Fije el código en producción. De esta forma, su integración mantendrá el comportamiento con el que fue probada cuando una versión futura modifique la respuesta.nd-version

Reglas de nomenclatura

• Los nombres de los campos están en formato snake_case en las solicitudes y respuestas: page_size, next_cursor, default_locale.

• Los parámetros de consulta tienen una sola ortografía. ?page_size=10 funciona. ?pageSize=10 se rechaza como parámetro desconocido con 400 validation_error.

• Los parámetros y campos del cuerpo desconocidos se rechazan con el código 400 validation_error, por lo que un error tipográfico nunca pasa desapercibido.

• La API utiliza sus propios sustantivos. Un centro de ayuda es un site, y una colección es un category. Las rutas tienen el formato /sites/{site_id}/categories.

• Las fechas son ISO 8601 , por ejemplo 2026-10-18T14:39:03+00:00.

Preguntas frecuentes

¿Qué sigue?

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

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

• Comience a usar la API REST Notiondesk