Política de "ús raonable" de les eines de càrrega massiva de dades (KB040)

Aquest document descriu la política de “fair use” de les eines de càrrega massiva de dades com l’API i les càrregues de dades en bloc conegudes com a KB020, i inclou indicacions relatives als límits de l’API.

API

L’API de Smartosh està dissenyada per facilitar la integració i sincronització de dades entre la plataforma Smart OSH i sistemes externs dels clients. El seu propòsit és permetre:

Intercanvi bidireccional d’informació entre sistemes corporatius
Actualització automatitzada de dades des de fonts externes (ERP, HRIS, sistemes de gestió, etc.)
Consultes puntuals per a integració amb eines de reporting o BI
Sincronització de dades amb altres sistemes de l’organització
Automatització de fluxos de treball que complementin l’ús de la plataforma

Ús no previst

L’API no està dissenyada ni s’ofereix per a:

Crear interfícies d’usuari alternatives que substitueixin significativament l’ús de la plataforma web de Smart OSH
Desenvolupar aplicacions completes que repliquin la funcionalitat principal de Smart OSH
Substituir l’accés normal d’usuaris a la plataforma per accés exclusiu via API
Extreure contínuament tota la base de dades per operar fora de Smart OSH

Principis Generals

L’API de Smart OSH està disponible per a tots els nostres clients sense un límit establert de consultes o actualitzacions, sota el principi d’ús “fair use” dels recursos de la plataforma.

Autenticació i gestió de sessions

L’autenticació a l’API de SmartOSH es realitza mitjançant HTTP Basic Authentication. En la primera crida, el client ha d’autenticar-se utilitzant les credencials d’usuari API. El client HTTP guardarà el token resultant del HTTP Authentication Challenge i les crides posteriors quedaran autenticades automàticament.

Les credencials d’accés (usuari i contrasenya) poden ser creades per l’administrador de SmartOSH des de la consola d’administració de la plataforma.

Gestió de sessions

Quan s’usi Basic Authentication és necessari que el client d’API mantingui la sessió entre crides. Existeixen dos mètodes equivalents:

Cookies de sessió: El client HTTP manté automàticament les cookies rebudes en la primera crida.
Header x-session: El client captura el valor de l’header x-session rebut en la primera resposta i el reenvia en totes les crides posteriors.

Si no es manté la sessió correctament:

Les crides seran extremadament lentes
Pot comprometre’s el rendiment de la subscripció del client
S’assolirà el límit de sessions simultànies

Límit de sessions

L’API té un límit de 50 identificadors de sessió diferents per usuari per hora. Quan es supera aquest límit, el servei rebutjarà les peticions amb el missatge:

“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.”

Causes comunes d’excés de sessions:

El mateix usuari API està sent compartit per diversos usuaris o sistemes reals
Els identificadors de sessió no s’estan conservant adequadament entre crides
No s’estan reutilitzant les cookies de sessió

Recomanacions:

Mantenir la sessió activa correctament mitjançant cookies o capçaleres x-session
Si múltiples sistemes necessiten accés simultani, distribuir les peticions entre diferents usuaris API
Verificar que el client HTTP està configurat per preservar cookies entre crides

Ús esperat

Actualitzacions de dades

L’API està dissenyada per rebre únicament dades que han experimentat canvis reals. Els clients han de:

Enviar actualitzacions només quan la informació hagi canviat efectivament
Implementar lògica de detecció de canvis abans de realitzar crides a l’API
NO enviar actualitzacions reiteratives de la mateixa informació sense modificacions

Límits tècnics de velocitat (Rate Limiting)

Encara que no existeix un límit dur de volum total, Smart OSH implementa controls de velocitat per garantir l’estabilitat del servei:

Límit màxim: 3.600 peticions per hora (equivalent a 60 peticions per minut)
Crides concurrents: 1. Les crides en paral·lel rebran un status code 429
Mecanisme de protecció: Quan el sistema detecta un ritme superior a aquests valors, s’activa automàticament un mecanisme de throttling que limitarà temporalment les peticions

Codis de resposta i maneig d’errors

Codis HTTP rellevants

Codi	Significat	Acció requerida
`200 OK`	Petició exitosa	Continuar normalment
`400 Bad Request`	Habitualment “You are using too many sessions”	Veure gestió de sessions
`401 Unauthorized`	Credencials invàlides o sessió expirada	Verificar credencials i reautenticar
`429 Too Many Requests`	Límit de velocitat superat	Implementar backoff i reintentar
`503 Service Unavailable`	Servei temporalment no disponible	Reintentar amb estratègia exponencial
`504 / 524 Gateway Timeout`	Timeout per bloqueig de recursos	Reintentar després d’un interval

Manteniment programat

Smart OSH realitza manteniments periòdics que poden resultar en codi 503 Service Unavailable. Les finestres de manteniment es notifiquen amb antelació. Els clients han d’implementar estratègies de reintent davant codis 503 per gestionar aquests períodes sense pèrdua de dades.

Bloquejos per operacions concurrents

La plataforma pot retenir o bloquejar temporalment l’accés a certs dades quan:

S’estan executant operacions massives (importacions, processos batch, etc.)
Altres usuaris estan realitzant operacions individuals sobre els mateixos recursos
Existeixen processos de càlcul intensius en curs

Durant aquests bloquejos l’API pot experimentar temps de resposta més prolongats o retornar codis 503 / 504 / 524. El client ha d’implementar reintents amb intervals creixents.

Estratègies de reintent recomanades

Backoff exponencial amb jitter:

Reintent 1: esperar 1–2 segons
Reintent 2: esperar 2–4 segons
Reintent 3: esperar 30–60 segons
Reintent 4: esperar 180–300 segons

Codis que requereixen reintent: 429, 503, 504, 524, errors de xarxa/timeout.

Codis que NO s’han de reintentar automàticament: 400, 401, 403, 404, 422.

Millors pràctiques

Consultes en bloc amb paginació — Utilitzar endpoints de consulta massiva per a grans volums. Mida de pàgina recomanada: 100–500 registres.
Estratègies de backoff — Implementar retrocés exponencial davant errors o respostes 429 / >500. Afegir jitter aleatori per evitar sincronització de reintents.
Detecció de canvis local — Mantenir un registre de l’estat de les dades al sistema client. Considerar l’ús de timestamps, checksums o hashes per detectar canvis.
Consolidació d’actualitzacions — Agrupar múltiples canvis en una sola petició quan l’API ho permeti. Utilitzar operacions batch quan estiguin disponibles.
Timeouts apropiats — Connexió: 10–30 segons. Lectura: 60–100 segons per a operacions complexes.

Headers informatius

L’API pot incloure els següents headers per monitoritzar l’ús:

x-throttled — Indica si les consultes es troben limitades pel servidor
x-requestsUserMinCount — Comptador de consultes realitzades en els últims 60 segons

Horaris recomanats

Per a operacions massives, eviti en la mesura del possible els horaris punta:

Evitar: 9:00–18:00 (CET)
Preferir: 20:00–7:00 (CET) per a càrregues massives
Coordinar amb suport per a operacions extraordinàries

Càrregues massives mitjançant Excel (KB020)

Propòsit

Les eines de càrrega massiva mitjançant arxius Excel (KB020) estan dissenyades per a:

Migracions inicials de dades en implementar SmartOSH
Actualitzacions massives puntuals quan existeixen canvis significatius en les dades
Càrregues incrementals de nous registres o modificacions de registres existents
Correccions massives de dades davant incidències identificades

Principi d’ús incremental

Les càrregues mitjançant KB020 han de seguir un model incremental, no de reemplaçament total:

Carregar únicament els registres que han canviat des de l’última càrrega
Incloure només les columnes amb valors modificats quan sigui possible
NO recarregar massivament tota la base de dades de forma periòdica
NO pujar arxius amb dades idèntiques a les ja existents a la plataforma
NO usar KB020 com a mètode habitual d’actualització de dades que canvien freqüentment

Impacte de les càrregues massives

Igual que amb l’API, cada càrrega de dades mitjançant KB020 desencadena validacions, recàlculs automàtics, notificacions per correu electrònic, activació de fluxos de treball i bloquejos temporals de recursos.

Les càrregues repetitives de dades sense canvis generen costos computacionals innecessaris, saturen els usuaris amb notificacions superflues i poden afectar el rendiment general de l’entorn del client.

Ús no apropiat de KB020

Les eines de càrrega massiva no s’han d’utilitzar per a:

Substituir les funcionalitats d’actualització de dades disponibles a la interfície web
Realitzar recàrregues sistemàtiques i periòdiques de la totalitat de les dades sense modificacions efectives
Actualitzar registres els valors dels quals no han experimentat canvis
Constituir el mètode principal de gestió i manteniment de dades en substitució de l’ús normal de la plataforma

Bones pràctiques per a càrregues en lot

Preparació de l’arxiu Excel:

Identifiqueu quins registres han canviat realment des de l’última càrrega
Exporteu des de SmartOSH l’estat actual si cal comparar
Incloeu només els registres modificats o nous amb les seves columnes identificadores (ID, Key, codi únic, etc.)

Freqüència recomanada:

Migracions inicials: una sola vegada en implementar
Actualitzacions normals: només quan hi hagi canvis significatius que ho justifiquin
Freqüència màxima recomanada: una càrrega diària
Per a actualitzacions freqüents, urgents o unitàries: utilitzeu l’API en lloc de KB020

Senyalitzacions d’ús inadequat:

Càrregues diàries o diverses vegades per setmana de les mateixes dades
Arxius amb milers de registres però pocs canvis reals
Càrregues automàtiques programades sense validació prèvia de canvis que generin molts errors

Intervenció en casos d’ús abusiu

Smartosh es reserva el dret de contactar clients el patró d’ús dels quals:

Superi sistemàticament els límits de velocitat establerts
Generi càrregues innecessàries mitjançant actualitzacions repetitives sense canvis
Comprometi el rendiment general de la plataforma
No implementi estratègies de reintent adequades

En aquests casos, treballarem amb el client per optimitzar la seva integració i garantir un ús sostenible del servei. SmartOSH es reserva el dret de limitar o restringir l’ús de l’API.

Disponibilitat i SLA

Disponibilitat objectiu: 99,5% (exclou manteniments programats i bloquejos de dades funcionals del propi entorn del client)
Suport tècnic: Disponible en horari laboral