🤖 Este artículo fue traducido por IA.
¿A quién va dirigido este artículo?
A los usuarios e integradores que consumen la API de Boond desde un script, un conector o una herramienta de automatización de terceros, y que desean optimizar su número de llamadas, tanto para mantenerse dentro de los límites como para construir una integración más limpia.
1. Rate limiting y cuota
Tu consumo está regulado por dos mecanismos independientes que se suman:
El rate limiting suaviza tu flujo a corto plazo, por minuto y por tramo de 10 segundos. Si vas demasiado rápido, la API responde temporalmente con
429 Too Many Requests. Los umbrales dependen del endpoint llamado. Este mecanismo está en proceso de despliegue y se aplicará a partir de finales de septiembre de 2026: dimensiona tu integración desde ahora.La cuota limita tu número total de llamadas al mes; este límite mensual depende de tu plan.
El detalle de los umbrales se describe en el artículo dedicado: Comprender los límites de llamadas de la API.
Algunas precisiones sobre lo que se contabiliza:
Solo se contabilizan las llamadas a la API: la navegación de tus empleados en la interfaz de Boond no cuenta para la cuota.
Una llamada fallida se contabiliza como cualquier otra: el contador se incrementa en la autenticación, incluso antes de procesar tu petición. Una integración que repite en bucle llamadas rechazadas consume su cuota para nada.
Las llamadas de Apps desarrolladas por terceros (por ejemplo, socios) no consumen tu cuota siempre que el modo de conexión utilice OAuth2 o JWTApp. Si compartes la información de acceso o la clave de cliente de tu administración, sus llamadas serán contabilizadas.
En caso de superar el límite y que el volumen no esté cubierto por tu cuota actual, puedes adquirir paquetes adicionales de APIs.
2. Reducir las llamadas superfluas
La primera fuente de ahorro son las llamadas que simplemente puedes no hacer. Y es más rentable de lo que parece: cada llamada repite toda la secuencia de autenticación—validación del token, resolución de tu instancia, carga de la cuenta y de sus derechos, conteo de la cuota. Nada se comparte de una llamada a otra. Por tanto, el número de llamadas, más que su contenido, es lo que pesa.
Haz caché de lo que cambia poco. Algunos datos normalmente no deberían cambiar a menudo: referencias, configuración, estructura de tu instancia. Recupéralos una vez, consérvalos de tu lado y actualízalos con una frecuencia razonable en lugar de en cada ejecución.
⚠️ Nota: la API no expone un mecanismo de revalidación—no hay ETag, ni respuesta de "nada ha cambiado". Tampoco confíes en la cabecera Last-Modified: se envía con la hora de la respuesta, no con la fecha de modificación del dato—si confías en ella, pensarás que todo ha cambiado en cada llamada. La fecha de última modificación se encuentra en la propia respuesta, en la ficha. Por tanto, tu caché debe basarse en una duración fija o en los webhooks (ver §3).
Solo hay una excepción útil: la respuesta de los parámetros de tu instancia lleva un número de versión, que cambia en cuanto se modifica la configuración. Es la única señal fiable para detectar que una referencia ha cambiado sin tener que comparar todo.
Guarda los datos fijos. Los datos históricos que ya no cambian—antiguos informes de actividad, facturas cerradas, proyectos finalizados—no necesitan ser extraídos repetidamente. Guárdalos una vez en tu sistema y solo vuelve a consultar los períodos recientes o susceptibles de cambiar.
No autentiques en cada paso. Un reflejo frecuente y costoso consiste en llamar a un endpoint de verificación como current-user antes de cada petición. La autenticación no cambia durante un proceso: un solo control al inicio de la sesión es suficiente.
Utiliza una cuenta dedicada a tu integración si está integrada en backend. Ejecutar un flujo sobre la cuenta nominativa de un empleado plantea dos problemas:
El flujo hereda su perímetro: todas las fichas que no tiene derecho a ver generan llamadas rechazadas, contabilizadas y repetidas en cada ciclo.
El día que ese empleado cambie de rol o deje la empresa, la integración no se detiene—continúa viendo menos datos, sin error visible.
Una cuenta de servicio, con un perímetro definido explícitamente, evita ambos problemas. Si usas una App integrada o que se apoya en los derechos del usuario conectado, la cuenta de servicio no tiene sentido y eludiría la configuración de derechos de Boond.
No vuelvas a pedir lo que ya te han denegado. Un acceso denegado no es un incidente pasajero: la ficha seguirá siendo inaccesible hasta que cambien los derechos. Memoriza la denegación y deja de pedirla en cada ciclo. Es un motivo frecuente y de los más costosos: decenas de miles de llamadas al mes, todas contabilizadas, para una respuesta ya conocida.
Recupera más datos por llamada—pero hazte la pregunta adecuada primero. El número de resultados por página es ajustable y dejarlo en el valor por defecto multiplica automáticamente tus llamadas. Dos advertencias:
Un valor fuera de rango no se ajusta al máximo: vuelve silenciosamente al valor por defecto. Verifica el número real de resultados devueltos en vez de suponer que tu parámetro fue aceptado.
Aumentar el tamaño de la página reduce el número de llamadas, no el coste de la petición. En colecciones grandes, una página muy grande puede ser más lenta que varias medianas, hasta superar tu tiempo de espera—y una llamada que interrumpes igualmente se ejecuta y se contabiliza.
Sobre todo, si recuperas un gran volumen solo para extraer una lista de identificadores y luego vuelves a consultar cada ficha una a una, es el propio mecanismo el que debes revisar: pagas dos veces. Pregúntate qué necesita realmente tu proceso antes de ajustar el tamaño de página.
Agrupa en lugar de una llamada por ficha. Las sub-recursos de una ficha son eficaces para consultar una; usadas para recorrer todas tus fichas, se convierten en el peor motivo—una llamada por entidad, repetida en cada ciclo. Es, con diferencia, lo que más incrementa el consumo observado. Siempre que una búsqueda permita recuperar varias entidades conocidas en una sola llamada, listando sus referencias, prefierela sistemáticamente—y aplica este reflejo en todas partes, no solo donde lo implementaste primero.
Evita las llamadas "por si acaso". Cada llamada debe responder a una necesidad real. Si no sabes si un dato ha cambiado, apunta al cambio (ver §3) en lugar de volver a descargar todo por precaución.
3. Sincronizarse con los cambios
Para los datos que cambian, la regla es simple: recupera solo lo que ha cambiado desde tu última consulta. Hay varias opciones, de la más simple a la más avanzada.
Limita tus extracciones a la ventana útil. Una extracción sin límite—"todo, cada vez"—aumenta innecesariamente tu consumo. Restringe siempre a la ventana que realmente necesitas, filtrando por fecha, período o perímetro. Una ventana demasiado amplia no solo cuesta en volumen: hace que las páginas se desborden y terminas pagando en paginación por datos que no usas. Una parte importante de las llamadas de una integración mal acotada existe solo por esta razón.
💡 Consejo: para construir cualquier llamada filtrada (extracción o registro de actividades), aplica el filtro deseado directamente en la interfaz de Boond y luego abre la pestaña Red de tu navegador: verás el endpoint exacto y sus parámetros, listos para reproducir en tu integración.
Pasa a incremental. Concretamente: memoriza la fecha de tu última ejecución y solo procesa el delta—lo que se ha creado o modificado desde entonces. Suele suponer una fuerte reducción del volumen de llamadas.
Cuestiónate la frecuencia. Es el factor más eficaz y a menudo más olvidado: antes de optimizar tus llamadas, pregúntate cuántas veces al día realmente necesitas hacerlas. Repetir un ciclo completo cada hora sobre informes de actividad, ausencias o proyectos—que no cambian catorce veces al día—multiplica el consumo sin aportar nada. Ajusta la frecuencia a la frescura que necesita tu uso, no a lo que permite tu planificador.
⚠️ Punto de atención: no todos los datos se pueden sincronizar por delta. Los tiempos, ausencias y registros de actividad no ofrecen filtro por fecha de modificación: en estas colecciones, no existe un "dame lo que ha cambiado". La buena práctica consiste en restringir mucho la ventana solicitada—la semana actual y la anterior en lugar de todo el año—y complementar con el registro de actividades para detectar cambios más antiguos.
Apunta con precisión a través del registro de actividades. Recoge las creaciones, modificaciones y eliminaciones. Consultado con filtros, te indica qué fichas han cambiado y, a menudo, qué campos, en un periodo dado—solo tienes que volver a recuperar esas, en vez de todo.
O pasa a eventos con los webhooks. Suscríbete a los eventos de creación, actualización y eliminación de las entidades que te interesan: Boond te notifica en tiempo real, en lugar de que consultes en bucle.
⚠️ Punto de atención: la entrega de webhooks es "best-effort"—plazo corto, sin reintentos. Si la frescura de tus datos depende solo de ellos, un evento perdido puede crear una brecha duradera y silenciosa. Prevé una red de seguridad diaria: una pasada de recuperación sobre el registro de actividades o una resincronización por delta en una ventana móvil de 24 a 48 horas. También es la única forma de ver las eliminaciones: una ficha eliminada desaparece de los resultados sin señal alguna, y una sincronización por fecha de modificación nunca te lo indicará.
4. Controlar tu flujo
Espacia las extracciones pesadas. Los endpoints de extracción, reporting y exportación están entre los más costosos, con los límites más estrictos. Resérvalos para procesos planificados y espaciados—horas valle, por lotes—en lugar de series seguidas.
Pide compresión. Las respuestas de la API están comprimidas, pero solo si tu cliente lo solicita mediante la cabecera Accept-Encoding: gzip, deflate. Sin ella, todo se transmite sin comprimir, varias veces más voluminoso. Es una línea de configuración en tu cliente HTTP y una de las mejoras más inmediatas—verifica que tu biblioteca no la elimine.
El caché de los reportings se decide con tu cliente. Los endpoints de reporting recalculan por defecto todos sus indicadores en cada llamada: son los más costosos de la API. Pueden servir un resultado en caché, pero no es un simple parámetro de petición: la opción depende de la configuración de la instancia, está desactivada por defecto y su duración—de varios días—la fija el cliente. Acordad su activación y duración: la ganancia es importante, siempre que aceptes la frescura correspondiente.
Reacciona correctamente a un 429. No es un error bloqueante, sino una señal temporal:
Respeta la cabecera
Retry-After: te indica cuántos segundos esperar antes de reintentar. Nunca reintentes inmediatamente.Aplica un back-off progresivo en ausencia de otra señal—1 s, 2 s, 4 s, con algo de aleatoriedad—para evitar que todas tus llamadas se relancen a la vez.
Suaviza tu flujo en el cliente, con una cola y un techo por debajo del límite, en lugar de enviar ráfagas.
Aplicando estos principios, tu integración hará menos llamadas, se actualizará más rápido y contribuirá a la estabilidad de la plataforma.