Paginação | NueForm Docs

Todos os endpoints da API do NueForm que retornam listas de recursos suportam paginação baseada em páginas. Este guia cobre os parâmetros de query, o formato de resposta e padrões para iterar por todos os resultados.

Parâmetros de query

Controle a paginação com dois parâmetros de query:

Parâmetro	Tipo	Padrão	Descrição
`page`	integer	`1`	O número da página a recuperar (começando em 1).
`per_page`	integer	`20`	O número de itens por página. Mínimo: `1`, máximo: `100`.

Se per_page exceder 100, a API automaticamente o limita a 100. Valores menores que 1 assumem o padrão 1.

Exemplo de requisição

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 resposta

Respostas paginadas incluem um objeto meta junto com o 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 de meta

Campo	Tipo	Descrição
`page`	integer	O número da página atual.
`per_page`	integer	O número de itens por página (conforme aplicado).
`total`	integer	O número total de itens em todas as páginas.
`total_pages`	integer	O número total de páginas (calculado como `ceil(total / per_page)`).

Iterando por todas as páginas

Quando você precisar recuperar todos os itens de um endpoint de listagem, itere pelas páginas até 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

Gerador assíncrono (JavaScript)

Para grandes conjuntos de dados, use um gerador assíncrono para processar os itens conforme eles chegam em vez de carregar tudo na memória:

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);
}

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

Casos extremos

Resultados vazios

Se nenhum item corresponder à consulta, a API retorna um array data vazio com total: 0:

json

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

Página além do total

Solicitar um número de página além de total_pages retorna um array data vazio. Os valores de meta ainda refletem a coleção como um todo:

json

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

Parâmetros inválidos

Parâmetros de paginação inválidos são tratados de forma tolerante:

Entrada	Comportamento
`page=0` ou `page=-1`	Assume o padrão `1`
`page=abc`	Assume o padrão `1`
`per_page=0` ou `per_page=-5`	Assume o padrão `1`
`per_page=500`	Limitado a `100`
`per_page=abc`	Assume o padrão `20`

Boas práticas

Use o `per_page` máximo para recuperação em massa

Ao buscar todos os recursos, defina per_page=100 para minimizar o número de chamadas à API. Cada chamada conta para o seu limite de taxa.

Verifique `total_pages` antes de iterar

Sempre leia total_pages do objeto meta para determinar quando parar. Não itere indefinidamente nem presuma um número fixo de páginas.

Adicione um atraso entre páginas para grandes conjuntos de dados

Se você estiver buscando muitas páginas, adicione um pequeno atraso entre as requisições para evitar atingir os limites de taxa:

javascript

// Add a 200ms delay between page requests
await new Promise((resolve) => setTimeout(resolve, 200));

Faça cache do total quando apropriado

Se você só precisa da contagem total (por exemplo, para exibir "47 formulários"), solicite per_page=1 e leia meta.total para minimizar a transferência de dados:

curl

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

Os resultados da paginação refletem o estado dos dados no momento de cada requisição. Se itens forem criados ou excluídos entre as requisições de página, você pode ver duplicatas ou perder itens. Para snapshots consistentes, busque todas as páginas rapidamente ou use webhooks para atualizações em tempo real.