Visión general
Una herramienta HTTP personalizada permite que el Robô llame a tu API. Cuando esa API devuelve listas, casi siempre las devuelve en páginas — y sin configurarlo el Robô lee solo la primera y responde con una parte de los datos, sin saber que falta el resto.
La Paginación lo resuelve. Le indicas de qué tipo es, dónde están los ítems en la respuesta y cuántas páginas recorrer. Y, opcionalmente, cuántos ítems pedir por página.
Requisitos previos
- Un Robô con al menos una herramienta HTTP personalizada configurada.
- Saber cómo pagina tu API: por número de página o por cursor.
- Acceso de administrador de la cuenta.
Paso a paso
- Abre Configuración → Robôs y edita el Robô.
- Ve a Herramientas personalizadas y abre la herramienta.
- En Paginación, elige el tipo: Sin paginación, Número de página o Cursor.
- Completa los campos de paginación (ver la tabla abajo).
- Guarda.
Configuración y opciones
| Campo | Para qué sirve |
|---|---|
| Tipo | Sin paginación, Número de página o Cursor |
| Param de página/cursor | El nombre del parámetro que tu API usa para avanzar (page, cursor…) |
| Ruta de items (array) | Dónde está la lista de resultados en la respuesta |
| Ruta del próximo cursor | Dónde llega el cursor de la página siguiente (solo tipo cursor) |
| Página inicial | Desde qué página empezar |
| Máx. páginas | Tope de páginas que recorre una llamada |
| Param del tamaño de página | El nombre del parámetro de tamaño de tu API (per_page, limit…) |
| Ítems por página | El valor enviado en ese parámetro |
Los dos últimos son opcionales y van juntos: dejarlos vacíos significa no enviar el parámetro, y entonces la API decide el tamaño.
Casos de uso
- Una API cuyo valor por defecto son 100 ítems por página: define
per_page= 20. Cada página pasa a ser un trozo que cabe cómodamente en el contexto, y Máx. páginas controla hasta dónde ir. - Una API que devuelve todo de una vez: si acepta un parámetro de límite, úsalo. Una respuesta enorme de golpe consume el contexto del modelo y deja poco para razonar y para responder.
- Una API con cursor: completa Ruta del próximo cursor; el tamaño de página sigue aplicando.
Consejos, límites y buenas prácticas
- Empieza con un valor modesto (10 a 25) y súbelo solo si las respuestas salen incompletas.
- Un tamaño de página menor con Máx. páginas mayor suele ser mejor que una página gigante: el Robô puede parar en cuanto encontró lo que necesitaba.
- El parámetro tiene que existir en tu API. Un nombre que no conoce se suele ignorar en silencio — y te queda la impresión de que la configuración no tuvo efecto.
- Dejarlo vacío es una elección válida cuando el valor por defecto de la API ya es razonable.
Solución de problemas
El Robô responde con datos parciales. O la paginación está en Sin paginación, o Máx. páginas es demasiado bajo para el volumen que devuelve la consulta.
La herramienta tarda mucho. Cada página es una llamada HTTP. Baja Máx. páginas, o sube los ítems por página para traer el mismo volumen en menos idas y vueltas.
Cambié los ítems por página y no cambió nada. Confirma el nombre del parámetro con la
documentación de tu API — per_page, limit, page_size y pageSize son todos comunes, y solo uno
es el correcto.
La lista llega vacía. La Ruta de items no apunta al array correcto en la respuesta.