🤖 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 rendimiento a corto plazo, por minuto y por intervalos 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 colaboradores en la interfaz de Boond no cuenta para la cuota.
Una llamada fallida se contabiliza como las demás: el contador se incrementa en la autenticación, incluso antes de que se procese tu solicitud. Una integración que repite en bucle llamadas rechazadas consume su cuota para nada.
Las llamadas de Apps desarrolladas por terceros (socios, por ejemplo) no consumen tu cuota siempre que el modo de conexión utilice OAuth2 o JWTApp. Si compartes la información de acceso/login o la clave de cliente de tu administración, sus llamadas sí serán contabilizadas.
En caso de superar el límite y el volumen no esté cubierto por tu cuota actual, puedes suscribirte a paquetes adicionales de APIs.
2. Reducir llamadas innecesarias
La primera fuente de ahorro son las llamadas que simplemente no realizas. 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 sus derechos, cómputo de la cuota. Nada se comparte de una llamada a otra. Por tanto, es el número de llamadas, más que su contenido, lo que pesa.
Cachea lo que cambia poco. Algunos datos normalmente no cambian con frecuencia: datos de referencia, configuración, estructura de tu instancia. Recupéralos una vez, guárdalos de tu lado y actualízalos con una frecuencia razonable en vez 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 devuelve con la hora de la respuesta, no con la fecha de modificación del dato — confiar en ella te haría pensar que todo acaba de cambiar, en cada llamada. La fecha de última modificación se lee en la propia respuesta, en el registro. Por tanto, tu caché debe basarse en una vida útil fija, o en los webhooks (ver §3).
Una única 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 un dato de referencia ha cambiado sin tener que comparar todo.
Guarda los datos estáticos. 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 periodos 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 solicitud. La autenticación no cambia durante un proceso: un solo control al inicio de la sesión es suficiente.
Utiliza una cuenta dedicada para tu integración si está integrada en backend. Ejecutar un flujo con la cuenta nominativa de un colaborador plantea dos problemas:
El flujo hereda su perímetro: todos los registros a los que no tiene acceso generan llamadas rechazadas, contabilizadas y repetidas en cada ciclo.
El día que ese colaborador 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 te ha sido denegado. Un acceso denegado no es un incidente pasajero: el registro seguirá siendo inaccesible hasta que cambien los derechos. Memoriza el rechazo y deja de solicitarlo cada vez. Es un motivo frecuente y uno de los más costosos: decenas de miles de llamadas al mes, todas contabilizadas, para una respuesta conocida de antemano.
Recupera más datos por llamada — pero hazte primero la pregunta adecuada. El número de resultados por página es ajustable, y dejarlo en el valor por defecto multiplica tus llamadas. Dos advertencias, sin embargo:
Un valor fuera de límite no se ajusta al máximo: vuelve silenciosamente al valor por defecto. Verifica el número de resultados realmente devueltos en vez de suponer que tu parámetro ha sido aceptado.
Aumentar el tamaño de la página reduce el número de llamadas, no el coste de la solicitud. En colecciones pesadas, una página muy grande puede ser más lenta que varias medianas, llegando a superar tu tiempo de espera — y una llamada que interrumpes igualmente se ejecuta hasta el final y se contabiliza.
Sobre todo, si recuperas un gran volumen solo para extraer una lista de IDs y luego llamar a los registros uno a uno, es el propio mecanismo el que hay que revisar: pagas dos veces. Pregúntate qué necesita realmente tu proceso antes de ajustar el tamaño de página.
Agrupa en vez de una llamada por registro. Las sub-recursos de un registro son eficaces para consultar uno; usadas para recorrer todos tus registros, se convierten en el peor de los motivos — una llamada por entidad, repetida en cada ciclo. Es, con diferencia, lo que más incrementa el consumo. Siempre que una búsqueda te 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 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 vez de volver a descargar todo por precaución.
3. Sincronizarse con los cambios
Para los datos que cambian, la regla es simple: solo recupera lo que ha cambiado desde tu última consulta. Hay varias formas de hacerlo, de la más simple a la más precisa.
Limita tus extracciones a la ventana útil. Una extracción sin límites — "todo, cada vez" — incrementa 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 acabas pagando en paginación por datos que no utilizas. 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 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 el más olvidado: antes de optimizar tus llamadas, pregúntate cuántas veces al día realmente necesitas ejecutarlas. 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 cadencia a la frescura que tu uso necesita, no a lo que permite tu planificador.
⚠️ Punto de atención: no todos los datos se sincronizan por delta. Los tiempos, ausencias y registros de actividad no ofrecen filtro por fecha de modificación: en estas colecciones, no existe el "dame lo que ha cambiado". La buena práctica consiste en restringir fuertemente la ventana solicitada — la semana en curso y la anterior en vez de todo el año — y complementar con el registro de actividades para detectar cambios más antiguos.
Apunta con precisión usando el registro de actividades. Recoge las creaciones, modificaciones y eliminaciones. Consultado con filtros, te indica qué registros han cambiado, y a menudo qué campos, en un periodo dado — solo tienes que volver a recuperar esos, en vez de todo.
O pásate al modelo de eventos con 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 vez de que consultes en bucle.
⚠️ Punto de atención: la entrega de webhooks es "best-effort" — corto plazo, sin reintentos. Si la frescura de tus datos depende solo de ellos, un evento perdido puede crear una diferencia 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. Es también la única forma de ver las eliminaciones: un registro eliminado desaparece de los resultados sin que nada lo indique, y una sincronización por fecha de modificación nunca te lo mostrará.
4. Controlar el rendimiento
Espacia las extracciones pesadas. Los endpoints de extracción, reporting y exportación son de los más costosos, con los límites más estrictos. Resérvalos para procesos planificados y espaciados — horas valle, partición — en vez de series seguidas.
Solicita compresión. Las respuestas de la API se comprimen, 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 uno de los ahorros más inmediatos — verifica que tu librería no la elimine.
El caché de reporting 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 cacheado, pero no es un simple parámetro de solicitud: 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. Acuerda con él su activación y duración: el ahorro es importante, si aceptas la frescura correspondiente.
Gestiona correctamente 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. No reintentes nunca inmediatamente.Aplica un back-off progresivo si no hay otra señal — 1 s, 2 s, 4 s, con algo de aleatoriedad — para evitar que todas tus llamadas se reactiven a la vez.
Suaviza tu rendimiento en el cliente, con una cola y un techo por debajo del límite, en vez de enviar ráfagas.
Aplicando estos principios, tu integración llama menos, se actualiza más rápido y contribuye a la estabilidad de la plataforma.