Paginación | NueForm Docs

Todos los endpoints de la API de NueForm que devuelven listas de recursos soportan paginación basada en páginas. Esta guía cubre los parámetros de consulta, el formato de respuesta y los patrones para iterar a través de todos los resultados.

Parámetros de consulta

Controla la paginación con dos parámetros de consulta:

Parámetro	Tipo	Predeterminado	Descripción
`page`	entero	`1`	El número de página a recuperar (indexado desde 1).
`per_page`	entero	`20`	El número de elementos por página. Mínimo: `1`, máximo: `100`.

Si per_page excede 100, la API automáticamente lo limita a 100. Los valores menores a 1 se establecen por defecto en 1.

Ejemplo de solicitud

GET/api/v1/forms?page=2&per_page=25

curl

curl -X GET "https://app.nueform.com/api/v1/forms?page=2&per_page=25" \
  -H "Authorization: Bearer nf_your_api_key_here"

Formato de respuesta

Las respuestas paginadas incluyen un objeto meta junto con el array data:

json

{
  "data": [
    {
      "id": "clx1abc2d3e4f5g6h7i8j9k0",
      "title": "Customer Feedback",
      "status": "published",
      "created_at": "2026-01-15T09:30:00.000Z"
    },
    {
      "id": "clx2def3g4h5i6j7k8l9m0n1",
      "title": "Employee Survey",
      "status": "draft",
      "created_at": "2026-01-20T14:00:00.000Z"
    }
  ],
  "meta": {
    "page": 2,
    "per_page": 25,
    "total": 73,
    "total_pages": 3
  }
}

Campos Meta

Campo	Tipo	Descripción
`page`	entero	El número de página actual.
`per_page`	entero	El número de elementos por página (según lo aplicado).
`total`	entero	El número total de elementos en todas las páginas.
`total_pages`	entero	El número total de páginas (calculado como `ceil(total / per_page)`).

Iteración a través de todas las páginas

Cuando necesites recuperar todos los elementos de un endpoint de lista, itera a través de las páginas hasta que page exceda total_pages.

JavaScript

javascript

async function fetchAllForms() {
  const allForms = [];
  let page = 1;
  let totalPages = 1;

  do {
    const response = await fetch(
      `https://app.nueform.com/api/v1/forms?page=${page}&per_page=100`,
      {
        headers: {
          "Authorization": `Bearer ${process.env.NUEFORM_API_KEY}`,
        },
      }
    );

    const { data, meta } = await response.json();
    allForms.push(...data);
    totalPages = meta.total_pages;
    page++;
  } while (page <= totalPages);

  console.log(`Fetched ${allForms.length} forms in total.`);
  return allForms;
}

Python

python

import os
import requests

API_KEY = os.environ["NUEFORM_API_KEY"]
BASE_URL = "https://app.nueform.com/api/v1"

def fetch_all_forms():
    all_forms = []
    page = 1
    total_pages = 1

    while page <= total_pages:
        response = requests.get(
            f"{BASE_URL}/forms",
            headers={"Authorization": f"Bearer {API_KEY}"},
            params={"page": page, "per_page": 100},
        )
        body = response.json()
        all_forms.extend(body["data"])
        total_pages = body["meta"]["total_pages"]
        page += 1

    print(f"Fetched {len(all_forms)} forms in total.")
    return all_forms

Generador asíncrono (JavaScript)

Para conjuntos de datos grandes, usa un generador asíncrono para procesar elementos a medida que llegan en lugar de cargar todo en memoria:

javascript

async function* paginatedForms(perPage = 100) {
  let page = 1;
  let totalPages = 1;

  do {
    const response = await fetch(
      `https://app.nueform.com/api/v1/forms?page=${page}&per_page=${perPage}`,
      {
        headers: {
          "Authorization": `Bearer ${process.env.NUEFORM_API_KEY}`,
        },
      }
    );

    const { data, meta } = await response.json();
    totalPages = meta.total_pages;

    for (const form of data) {
      yield form;
    }

    page++;
  } while (page <= totalPages);
}

// Uso
for await (const form of paginatedForms()) {
  console.log(`Processing: ${form.title}`);
}

Casos especiales

Resultados vacíos

Si ningún elemento coincide con la consulta, la API devuelve un array data vacío con total: 0:

json

{
  "data": [],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 0,
    "total_pages": 0
  }
}

Página más allá del total

Solicitar un número de página más allá de total_pages devuelve un array data vacío. Los valores de meta aún reflejan la colección completa:

json

{
  "data": [],
  "meta": {
    "page": 10,
    "per_page": 20,
    "total": 73,
    "total_pages": 4
  }
}

Parámetros inválidos

Los parámetros de paginación inválidos se manejan de forma elegante:

Entrada	Comportamiento
`page=0` o `page=-1`	Se establece por defecto en `1`
`page=abc`	Se establece por defecto en `1`
`per_page=0` o `per_page=-5`	Se establece por defecto en `1`
`per_page=500`	Se limita a `100`
`per_page=abc`	Se establece por defecto en `20`

Mejores prácticas

Usa el máximo de `per_page` para recuperación masiva

Al obtener todos los recursos, establece per_page=100 para minimizar el número de llamadas a la API. Cada llamada cuenta contra tu límite de velocidad.

Verifica `total_pages` antes de iterar

Siempre lee total_pages del objeto meta para determinar cuándo detenerte. No iteres indefinidamente ni asumas un número fijo de páginas.

Agrega un retraso entre páginas para conjuntos de datos grandes

Si estás obteniendo muchas páginas, agrega un pequeño retraso entre solicitudes para evitar alcanzar los límites de velocidad:

javascript

// Agrega un retraso de 200ms entre solicitudes de página
await new Promise((resolve) => setTimeout(resolve, 200));

Almacena en caché el total cuando sea apropiado

Si solo necesitas el conteo total (por ejemplo, para mostrar "47 formularios"), solicita per_page=1 y lee meta.total para minimizar la transferencia de datos:

curl

curl -X GET "https://app.nueform.com/api/v1/forms?per_page=1" \
  -H "Authorization: Bearer nf_your_api_key_here"

Los resultados de paginación reflejan el estado de los datos en el momento de cada solicitud. Si se crean o eliminan elementos entre solicitudes de página, podrías ver duplicados o perder elementos. Para instantáneas consistentes, obtén todas las páginas rápidamente o usa webhooks para actualizaciones en tiempo real.