Paginación

Enumere los puntos finales en los datos de devolución de API en las páginas. Históricamente, la plataforma ha utilizado dos esquemas de paginación; El esquema específico está documentado en cada punto final en la referencia interactiva.

Esquema 1: desplazamiento y X-Total-Count

Paginación clásica basada en desplazamiento. La solicitud acepta el parámetro de consulta limit (tamaño de página) y offset (cuántos registros omitir):

curl -H "Authorization: Bearer <TOKEN_PERSONAL_COMPLETO>" "https://your-domain/api/bots/BOT_ID/users?limit=50&offset=100"

El recuento total de registros se devuelve en el encabezado de respuesta X-Total-Count. Úselo para calcular el número de páginas: siga incrementando offset por limit mientras offset sea menor que el valor de X-Total-Count. El cuerpo de la respuesta es una serie de elementos de la página actual.

El desplazamiento tiene un límite máximo.

"Mientras offset es menor que X-Total-Count" no continúa para siempre. Un offset superior a 100 000 se rechaza con 400, en cada terminal que acepte una compensación. La respuesta dice qué hacer: limitar el filtro o utilizar la paginación del cursor.

Esto no es protección contra un error tipográfico sino protección para la base de datos: un desplazamiento hace que produzca y descarte cada fila omitida, por lo que offset=5000000 es un escaneo completo de la tabla para una página.

Si una lista tiene más de 100.000 registros, un desplazamiento no llegará al final de la misma. Las opciones:

• limitan la selección con los filtros del punto final (período, canal, estado), normalmente suficiente;
• cambie a un cursor si el punto final admite uno (esquema 2 a continuación; las listas de registros de pagos y cobros, por ejemplo, admiten ambos);
• si realmente necesita todo el conjunto de datos, utilice la exportación de la sección correspondiente en lugar de páginas ambulantes.

El límite de tamaño de página difiere según el punto final

No existe un máximo único para limit: diferentes listas usan diferentes: 200, 500 y 1000 ocurren. El valor exacto se encuentra en la página del endpoint en la referencia.

Lo que hacen los puntos finales con un limit de gran tamaño también difiere, y eso importa más que los números:

• algunos rechazan la solicitud con 400 y un mensaje como "el límite debe ser como máximo 500, obtuve 5000";
• otros vuelven silenciosamente al valor predeterminado (generalmente 100) y devuelven una página más pequeña de la que usted solicitó.

De ahí la regla: nunca asuma que recibió una página del tamaño que solicitó. Mire la longitud de la matriz que obtuvo, no su propio limit, y avance offset según la cantidad de elementos realmente devueltos. De lo contrario, en un punto final del segundo tipo, avanza 5000 después de recibir 100 y omite el 98% de los datos sin ver ningún error.

Por la misma razón, no trate una página vacía como la única señal del final: use X-Total-Count y el recuento de elementos real juntos.

Esquema 2: cursor antes y has_more

Paginación basada en cursor para fuentes ordenadas por tiempo (por ejemplo, mensajes de diálogo). La solicitud acepta limit y un cursor before opcional: el identificador o marcador del último elemento ya recibido:

curl -H "Authorization: Bearer <TOKEN_PERSONAL_COMPLETO>" "https://your-domain/api/bots/BOT_ID/users/USER_ID/dialog?limit=50&before=CURSOR"

La respuesta contiene una página de elementos y un Bandera has_more. Mientras has_more sea true, repita la solicitud pasando el cursor del último elemento recibido como before. Cuando has_more es false, habrá llegado a la última página.

Qué esquema utilizar

Usted no elige el esquema: el punto final lo determina. Las listas de estilo de referencia suelen utilizar offset y X-Total-Count; Los feeds ordenados por tiempo utilizan el cursor before y has_more. Siempre revisa la página del endpoint en la referencia.

¿Qué sigue?

• Inicio rápido de API: primeras solicitudes.
• Errores: códigos de estado.
• Límites de tarifas: límites de solicitudes.