Paginación
Cómo recibir una lista larga por partes sin saltarte registros. Tamaño de página, offset y continuación con el cursor before.
En esta página
La API devuelve las listas largas, como las de clientes o mensajes, en partes llamadas páginas. Pedir las páginas siguientes se llama paginación. Así, tu programa no necesita descargar todo el historial en una sola solicitud.
Hay dos maneras de indicar por dónde continuar: omitir un número de registros ya leídos (desplazamiento) o enviar un marcador de la última posición leída (cursor). La referencia de la API indica cuál usa cada endpoint.
Esquema 1: desplazamiento y X-Total-Count
El parámetro limit determina el tamaño de la página y offset indica cuántos registros hay que omitir. Por ejemplo, limit=50&offset=100 solicita hasta 50 registros después de los primeros 100. Estos parámetros se añaden a la dirección después de ?:
curl -H "Authorization: Bearer <TOKEN_PERSONAL>" \
"https://tu-dominio/api/bots/BOT_ID/users?limit=50&offset=100"
El número total de registros viene en el encabezado de respuesta X-Total-Count. Después de cada página, aumenta offset en el número de elementos recibidos, no en el límite solicitado. Continúa mientras offset sea menor que X-Total-Count. El cuerpo de la respuesta contiene un array con los elementos de la página actual.
El desplazamiento tiene un máximo
No puedes avanzar indefinidamente: un offset superior a 100 000 se rechaza con 400 en cualquier endpoint que admita desplazamiento. La respuesta indica que debes reducir la selección con filtros o usar un cursor.
Un desplazamiento grande carga la base de datos porque tiene que procesar las filas que va a omitir. Para listas grandes, usa filtros, un cursor o una exportación.
Si la lista supera los 100 000 registros, el desplazamiento no permite llegar hasta el final. Tienes estas opciones:
- reducir la selección con los filtros del endpoint, por ejemplo período, canal o estado;
- usar un cursor si el endpoint lo admite; las listas de pagos y de registros de colecciones, por ejemplo, admiten ambos esquemas;
- usar la exportación del apartado correspondiente si necesitas todos los datos.
El máximo de limit depende del endpoint
No hay un máximo único para limit: según la lista, puede ser 200, 500 o 1000. Consulta el valor exacto en la página del endpoint en la referencia.
Los endpoints también responden de distintas formas a un limit demasiado alto:
- algunos rechazan la solicitud con
400y un mensaje como «limit must be at most 500, got 5000»; - otros usan sin avisar el valor predeterminado, normalmente 100, y devuelven una página más pequeña que la solicitada.
Por tanto, no supongas que recibiste tantos elementos como pediste. Comprueba la longitud del array recibido y aumenta offset solo en esa cantidad. Si pediste 5000, recibiste 100 y aun así avanzas 5000, te saltarás el 98 % de los datos sin recibir ningún error.
Tampoco uses una página vacía como única señal de que terminaste: comprueba conjuntamente X-Total-Count y la cantidad de elementos recibidos.
Esquema 2: cursor before y has_more
Este esquema sirve para listas ordenadas por tiempo, como los mensajes de una conversación. La solicitud acepta limit y, opcionalmente, before: un identificador o marcador del último elemento ya recibido.
curl -H "Authorization: Bearer <TOKEN_PERSONAL>" \
"https://tu-dominio/api/bots/BOT_ID/users/USER_ID/dialog?limit=50&before=CURSOR"
La respuesta incluye una página y el indicador has_more. Mientras sea true, repite la solicitud pasando como before el cursor del último elemento recibido. Cuando has_more sea false, habrás llegado a la última página.
Qué esquema utilizar
El esquema lo determina el endpoint. Los listados de referencia suelen usar desplazamiento y X-Total-Count; las listas ordenadas por tiempo suelen usar before y has_more. Comprueba siempre la página del endpoint en la referencia.
Qué sigue
- Inicio rápido de la API: primeras solicitudes.
- Errores de la API: códigos de estado.
- Límites y tamaños: restricciones de las solicitudes.