🤖 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 estar cómodos con 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 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 oferta.
El detalle de los umbrales está descrito 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 entra en la cuota.
Una llamada fallida se contabiliza igual que las demás: el contador se incrementa en la autenticación, incluso antes de procesar tu solicitud. 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/login o la clave cliente de tu administración, sus llamadas serán contabilizadas.
En caso de exceder el límite y que el volumen no esté cubierto por tu cuota actual, puedes suscribirte a packs adicionales de APIs.
2. Reducir llamadas superfluas
La primera fuente de ahorro son las llamadas que simplemente no se hacen. 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 la instancia, carga de la cuenta y sus derechos, contabilización de la cuota. Nada se comparte de una llamada a la siguiente. Por eso 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, consérvalos en tu sistema y actualízalos a una frecuencia razonable en vez de en cada ejecución.
⚠️ Nota: La API no expone un mecanismo de revalidación—no ETag, no respuesta "nada ha cambiado". No 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 concluir que todo ha cambiado en cada llamada. La fecha de última modificación se lee en la propia respuesta, en la ficha. Tu cache debe basarse en una duración fija o en 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 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 re-extraídos en bucle. Guárdalos una vez en tu sistema y luego solo consulta los periodos recientes o susceptibles de cambiar.
No autentiques en cada etapa. 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: basta un solo control al inicio de la sesión.
Usa una cuenta dedicada para tu integración si está integrada en backend. Ejecutar un flujo en la cuenta nominativa de un colaborador plantea dos problemas:
El flujo hereda su perímetro: todas las fichas que no tiene derecho a ver producen 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 explícitamente definido, evita ambos problemas. Si utilizas una App integrada o basada en los derechos del usuario conectado, la cuenta de servicio no tiene sentido y vendría a saltarse la configuración de derechos de Boond.
No vuelvas a pedir lo que te fue denegado. Un rechazo de acceso no es un incidente pasajero: la ficha seguirá siendo inaccesible hasta que los derechos cambien. Memoriza el rechazo y deja de solicitarla cada vez. Es un motivo frecuente y 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 correcta. El número de resultados por página es ajustable, y dejarlo en su valor por defecto multiplica mecánicamente 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 real de resultados devueltos en vez de asumir que tu parámetro fue aceptado.
Aumentar el tamaño de 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, incluso superar tu tiempo de espera—y una llamada interrumpida se ejecuta hasta el final y se contabiliza.
Sobre todo, si recuperas un gran volumen solo para extraer una lista de identificadores y luego vuelves a consultar las fichas una a una, es el propio mecanismo lo 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 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 aumenta el consumo. 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 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 varios métodos, del más simple al más preciso.
Limita tus extracciones a la ventana útil. Una extracción sin límites—"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 limitada 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. Esto suele reducir mucho el volumen de llamadas.
Cuestiona la frecuencia. Es el método más eficaz y el 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 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 en delta. Los tiempos, ausencias y registros de actividades no ofrecen filtro por fecha de modificación: en estas colecciones, no existe "dame lo que ha cambiado". La buena práctica consiste en restringir mucho la ventana solicitada—la semana actual y la anterior en vez de el año entero—y completar con el registro de actividades para detectar cambios más antiguos.
Apunta con precisión usando el registro de actividades. Este registra 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 recorrer todo.
O pasa a 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"—plazo corto, sin reintentos. Si tu frescura de 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 en 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 que nada lo indique, y una sincronización por fecha de modificación nunca te lo mostrará.
4. Controlar el 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, segmentación—en vez de series seguidas.
Pide compresión. Las respuestas de la API se comprimen, pero solo si tu cliente lo indica, mediante la cabecera Accept-Encoding: gzip, deflate. Sin ella, todo transita sin comprimir, varias veces más voluminoso. Es una línea de configuración en tu cliente HTTP y uno de los beneficios más inmediatos—verifica que tu biblioteca no la elimine.
El cache de reporting se decide con tu cliente. Los endpoints de reporting recalculan por defecto todos sus indicadores clave 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 beneficio 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 reinicien a la vez.
Suaviza tu flujo 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.