Política de "fair use" de las herramientas de carga masiva de datos (KB040)

Este documento describe la política de “fair use” de las herramientas de carga masiva de datos como la API y las cargas de datos en bloque conocidas como KB020, e incluye indicaciones relativas a los límites de la API.

API

La API de Smartosh está diseñada para facilitar la integración y sincronización de datos entre la plataforma Smart OSH y sistemas externos de los clientes. Su propósito es permitir:

Intercambio bidireccional de información entre sistemas corporativos
Actualización automatizada de datos desde fuentes externas (ERP, HRIS, sistemas de gestión, etc.)
Consultas puntuales para integración con herramientas de reporting o BI
Sincronización de datos con otros sistemas de la organización
Automatización de flujos de trabajo que complementen el uso de la plataforma

Uso no previsto

La API no está diseñada ni se ofrece para:

Crear interfaces de usuario alternativas que sustituyan significativamente el uso de la plataforma web de Smart OSH
Desarrollar aplicaciones completas que repliquen la funcionalidad principal de Smart OSH
Sustituir el acceso normal de usuarios a la plataforma por acceso exclusivo vía API
Extraer continuamente toda la base de datos para operar fuera de Smart OSH

Principios Generales

La API de Smart OSH está disponible para todos nuestros clientes sin un límite establecido de consultas o actualizaciones, bajo el principio de uso “fair use” de los recursos de la plataforma.

Autenticación y gestión de sesiones

La autenticación en la API de SmartOSH se realiza mediante HTTP Basic Authentication. En la primera llamada, el cliente debe autenticarse utilizando las credenciales de usuario API. El cliente HTTP guardará el token resultante del HTTP Authentication Challenge y las llamadas subsiguientes quedarán autenticadas automáticamente.

Las credenciales de acceso (usuario y contraseña) pueden ser creadas por el administrador de SmartOSH desde la consola de administración de la plataforma.

Gestión de sesiones

Cuando se use Basic Authentication es necesario que el cliente de API mantenga la sesión entre llamadas. Existen dos métodos equivalentes:

Cookies de sesión: El cliente HTTP mantiene automáticamente las cookies recibidas en la primera llamada.
Header x-session: El cliente captura el valor del header x-session recibido en la primera respuesta y lo reenvía en todas las llamadas subsiguientes.

Si no se mantiene la sesión correctamente:

Las llamadas serán extremadamente lentas
Puede comprometerse el rendimiento de la suscripción del cliente
Se alcanzará el límite de sesiones simultáneas

Límite de sesiones

La API tiene un límite de 50 identificadores de sesión distintos por usuario por hora. Cuando se supera este límite, el servicio rechazará las peticiones con el mensaje:

“You are using too many sessions. Please make sure that you are reusing your sessions using cookies. For more information please check the reference guide KB008.”

Causas comunes de exceso de sesiones:

El mismo usuario API está siendo compartido por varios usuarios o sistemas reales
Los identificadores de sesión no se están conservando adecuadamente entre llamadas
No se están reutilizando las cookies de sesión

Recomendaciones:

Mantener la sesión activa correctamente mediante cookies o encabezados x-session
Si múltiples sistemas necesitan acceso simultáneo, distribuir las peticiones entre diferentes usuarios API
Verificar que el cliente HTTP está configurado para preservar cookies entre llamadas

Uso esperado

Actualizaciones de datos

La API está diseñada para recibir únicamente datos que han experimentado cambios reales. Los clientes deben:

Enviar actualizaciones solo cuando la información haya cambiado efectivamente
Implementar lógica de detección de cambios antes de realizar llamadas a la API
NO enviar actualizaciones reiterativas de la misma información sin modificaciones

Límites técnicos de velocidad (Rate Limiting)

Aunque no existe un límite duro de volumen total, Smart OSH implementa controles de velocidad para garantizar la estabilidad del servicio:

Límite máximo: 3.600 peticiones por hora (equivalente a 60 peticiones por minuto)
Llamadas concurrentes: 1. Las llamadas en paralelo recibirán un status code 429
Mecanismo de protección: Cuando el sistema detecta un ritmo superior a estos valores, se activa automáticamente un mecanismo de throttling que limitará temporalmente las peticiones

Códigos de respuesta y manejo de errores

Códigos HTTP relevantes

Código	Significado	Acción requerida
`200 OK`	Petición exitosa	Continuar normalmente
`400 Bad Request`	Habitualmente “You are using too many sessions”	Ver gestión de sesiones
`401 Unauthorized`	Credenciales inválidas o sesión expirada	Verificar credenciales y reautenticar
`429 Too Many Requests`	Límite de velocidad superado	Implementar backoff y reintentar
`503 Service Unavailable`	Servicio temporalmente no disponible	Reintentar con estrategia exponencial
`504 / 524 Gateway Timeout`	Timeout por bloqueo de recursos	Reintentar después de un intervalo

Mantenimiento programado

Smart OSH realiza mantenimientos periódicos que pueden resultar en código 503 Service Unavailable. Las ventanas de mantenimiento se notifican con antelación. Los clientes deben implementar estrategias de reintento ante códigos 503 para manejar estos periodos sin pérdida de datos.

Bloqueos por operaciones concurrentes

La plataforma puede retener o bloquear temporalmente el acceso a ciertos datos cuando:

Se están ejecutando operaciones masivas (importaciones, procesos batch, etc.)
Otros usuarios están realizando operaciones individuales sobre los mismos recursos
Existen procesos de cálculo intensivos en curso

Durante estos bloqueos la API puede experimentar tiempos de respuesta más prolongados o devolver códigos 503 / 504 / 524. El cliente debe implementar reintentos con intervalos crecientes.

Estrategias de reintento recomendadas

Backoff exponencial con jitter:

Reintento 1: esperar 1–2 segundos
Reintento 2: esperar 2–4 segundos
Reintento 3: esperar 30–60 segundos
Reintento 4: esperar 180–300 segundos

Códigos que requieren reintento: 429, 503, 504, 524, errores de red/timeout.

Códigos que NO deben reintentarse automáticamente: 400, 401, 403, 404, 422.

Mejores prácticas

Consultas en bloque con paginación — Utilizar endpoints de consulta masiva para grandes volúmenes. Tamaño de página recomendado: 100–500 registros.
Estrategias de backoff — Implementar retroceso exponencial ante errores o respuestas 429 / >500. Añadir jitter aleatorio para evitar sincronización de reintentos.
Detección de cambios local — Mantener un registro del estado de los datos en el sistema cliente. Considerar el uso de timestamps, checksums o hashes para detectar cambios.
Consolidación de actualizaciones — Agrupar múltiples cambios en una sola petición cuando la API lo permita. Utilizar operaciones batch cuando estén disponibles.
Timeouts apropiados — Conexión: 10–30 segundos. Lectura: 60–100 segundos para operaciones complejas.

Headers informativos

La API puede incluir los siguientes headers para monitorizar el uso:

x-throttled — Indica si las consultas se encuentran limitadas por el servidor
x-requestsUserMinCount — Contador de consultas realizadas en los últimos 60 segundos

Horarios recomendados

Para operaciones masivas, evite en la medida de lo posible los horarios pico:

Evitar: 9:00–18:00 (CET)
Preferir: 20:00–7:00 (CET) para cargas masivas
Coordinar con soporte para operaciones extraordinarias

Cargas masivas mediante Excel (KB020)

Propósito

Las herramientas de carga masiva mediante archivos Excel (KB020) están diseñadas para:

Migraciones iniciales de datos al implementar SmartOSH
Actualizaciones masivas puntuales cuando existen cambios significativos en los datos
Cargas incrementales de nuevos registros o modificaciones de registros existentes
Correcciones masivas de datos ante incidencias identificadas

Principio de uso incremental

Las cargas mediante KB020 deben seguir un modelo incremental, no de reemplazo total:

Cargar únicamente los registros que han cambiado desde la última carga
Incluir solo las columnas con valores modificados cuando sea posible
NO recargar masivamente toda la base de datos de forma periódica
NO subir archivos con datos idénticos a los ya existentes en la plataforma
NO usar KB020 como método habitual de actualización de datos que cambian frecuentemente

Impacto de las cargas masivas

Al igual que con la API, cada carga de datos mediante KB020 desencadena validaciones, recálculos automáticos, notificaciones por correo electrónico, activación de flujos de trabajo y bloqueos temporales de recursos.

Las cargas repetitivas de datos sin cambios generan costes computacionales innecesarios, saturan a los usuarios con notificaciones superfluas y pueden afectar al rendimiento general del entorno del cliente.

Uso no apropiado de KB020

Las herramientas de carga masiva no deben utilizarse para:

Reemplazar las funcionalidades de actualización de datos disponibles en la interfaz web
Realizar recargas sistemáticas y periódicas de la totalidad de los datos sin modificaciones efectivas
Actualizar registros cuyos valores no han experimentado cambios
Constituir el método principal de gestión y mantenimiento de datos en sustitución del uso normal de la plataforma

Buenas prácticas para cargas en lote

Preparación del archivo Excel:

Identifique qué registros han cambiado realmente desde la última carga
Exporte desde SmartOSH el estado actual si necesita comparar
Incluya solo los registros modificados o nuevos con sus columnas identificadoras (ID, Key, código único, etc.)

Frecuencia recomendada:

Migraciones iniciales: una sola vez al implementar
Actualizaciones normales: solo cuando haya cambios significativos que lo justifiquen
Frecuencia máxima recomendada: una carga diaria
Para actualizaciones frecuentes, urgentes o unitarias: utilice la API en lugar de KB020

Señales de uso inadecuado:

Cargas diarias o varias veces por semana de los mismos datos
Archivos con miles de registros pero pocos cambios reales
Cargas automáticas programadas sin validación previa de cambios que generen muchos errores

Intervención en casos de uso abusivo

Smartosh se reserva el derecho de contactar a clientes cuyo patrón de uso:

Supere sistemáticamente los límites de velocidad establecidos
Genere cargas innecesarias mediante actualizaciones repetitivas sin cambios
Comprometa el rendimiento general de la plataforma
No implemente estrategias de reintento adecuadas

En estos casos, trabajaremos con el cliente para optimizar su integración y garantizar un uso sostenible del servicio. SmartOSH se reserva el derecho de limitar o restringir el uso de la API.

Disponibilidad y SLA

Disponibilidad objetivo: 99,5% (excluye mantenimientos programados y bloqueos de datos funcionales del propio entorno del cliente)
Soporte técnico: Disponible en horario laboral