Cómo Funciona la Paginación

La API GraphQL de Legalesign utiliza paginación basada en cursor siguiendo la especificación de conexión Relay. Cada lista de elementos — documentos, plantillas, contactos, facturas — usa este mismo patrón.

El Patrón de Conexión

La terminología proviene de la teoría de grafos — nodos son puntos, aristas son líneas que los conectan. En la API, una arista describe la relación entre dos tipos y puede llevar metadatos adicionales (como qué permisos tiene un User en un Group).

Cuando consultas una lista, no obtienes un arreglo simple. Obtienes un objeto conexión con tres partes:

documentConnection(first: 20) {
  documents { ... }     # the items (shortcut)
  totalCount            # total matching items
  pageInfo {            # pagination cursors
    startCursor
    endCursor
    hasNextPage
    hasPreviousPage
  }
}

¿Por Qué No Un Simple Arreglo?

La paginación basada en cursor es estable. A diferencia de la paginación por desplazamiento (page=2), los cursores no se rompen cuando se agregan o eliminan elementos entre solicitudes. Esto importa cuando los documentos se están enviando y firmando en tiempo real.

Obtener la Primera Página

Usa first para limitar los resultados. Cuando pagines a través de un conjunto completo de resultados en orden de creación, pasa "0" o "START" como argumento after en tu primera llamada para señalar que estás comenzando una secuencia paginada:

query {
  group(id: "grpYourGroupId") {
    documentConnection(first: 100, after: "0") {
      documents {
        id
        name
        status
        created
      }
      pageInfo {
        endCursor
        hasNextPage
      }
      totalCount
    }
  }
}

Obtener la Página Siguiente

Si hasNextPage es true, pasa endCursor como argumento after:

query {
  group(id: "grpYourGroupId") {
    documentConnection(first: 100, after: "eyJpZCI6ImRvYzEyMyJ9") {
      documents {
        id
        name
        status
        created
      }
      pageInfo {
        endCursor
        hasNextPage
      }
      totalCount
    }
  }
}

Repite hasta que hasNextPage sea false.

Argumentos de Paginación

Todas las conexiones aceptan estos argumentos:

Argumento	Tipo	Descripción
first	Int	Número de elementos a devolver desde el inicio
after	ID	Cursor a partir del cual empezar (para paginación hacia adelante)
last	Int	Número de elementos a devolver desde el final
before	ID	Cursor a partir del cual empezar (para paginación hacia atrás)

La mayoría de las conexiones también aceptan argumentos de filtro específicos para el tipo de datos. Por ejemplo, documentConnection acepta from, to, status, search, sendType y sender.

El Atajo de las Aristas

Las conexiones proporcionan tanto edges (con cursor por elemento) como una lista atajo. Para la mayoría de los casos de uso, el atajo es más simple:

# Shortcut — simpler, no per-item cursor
documentConnection(first: 20) {
  documents {
    id
    name
  }
  pageInfo {
    endCursor
    hasNextPage
  }
}

# Full edges — needed if you want per-item cursors
documentConnection(first: 20) {
  edges {
    node {
      id
      name
    }
    cursor
  }
  pageInfo {
    endCursor
    hasNextPage
  }
}

Usa el atajo a menos que necesites cursores individuales (por ejemplo, para eliminar un elemento específico y reanudar desde ese punto).

nota

totalCount devuelve el conteo de la página actual, no el total de todas las páginas. El costo de calcular un total global en potencialmente millones de registros hace que un total verdadero sea poco práctico.

Ejemplo en la Vida Real

Así es como la app Console de Legalesign pagina documentos usando scroll infinito con TanStack Query:

query queryInfiniteDocuments {
  group(id: "grpYourGroupId") {
    documentConnection(
      first: 100
      after: "eyJpZCI6ImRvYzEyMyJ9"
      sendType: SINGLE
      from: "2025-01-01T00:00:00Z"
      to: "2025-06-01T00:00:00Z"
    ) {
      documents {
        id
        name
        status
        senderName
        created
        recipients {
          id
          email
          status
          signedDateTime
        }
      }
      pageInfo {
        endCursor
        hasNextPage
      }
      totalCount
    }
  }
}

La app obtiene la primera página, luego en el desplazamiento usa endCursor como after para cargar el siguiente lote.

¿Qué Tipos Usan Conexiones?

Cada relación de lista en la API usa este patrón:

• Group.documentConnection, templateConnection, batchConnection, contactConnection, experienceConnection, scheduleConnection, attachmentConnection, memberConnection, invitationConnection, standardMessageConnection, contactGroupConnection, draftConnection, activityConnection
• Organisation.groupConnection, dataStopConnection, dataDeletionConnection, retentionConnection, userConnection, invoiceConnection, dataSubjectConnection
• Batch.documentConnection
• Billing.invoiceConnection
• Invoice.lineItemConnection
• Template.elementConnection, userSignatureConnection
• Document.elementConnection
• Recipient.elementConnection
• User.memberConnection, organisationConnection, supportTicketConnection