Politique d'utilisation équitable des outils de chargement massif de données (KB040)

Ce document décrit la politique de « fair use » des outils de chargement massif de données tels que l’API et les chargements de données en bloc connus sous le nom de KB020, et inclut des indications relatives aux limites de l’API.

API

L’API de Smartosh est conçue pour faciliter l’intégration et la synchronisation des données entre la plateforme Smart OSH et les systèmes externes des clients. Son objectif est de permettre :

Échange bidirectionnel d’informations entre systèmes d’entreprise
Mise à jour automatisée des données depuis des sources externes (ERP, HRIS, systèmes de gestion, etc.)
Requêtes ponctuelles pour intégration avec des outils de reporting ou BI
Synchronisation des données avec d’autres systèmes de l’organisation
Automatisation des flux de travail complétant l’utilisation de la plateforme

Usage non prévu

L’API n’est pas conçue ni proposée pour :

Créer des interfaces utilisateur alternatives qui remplaceraient significativement l’utilisation de la plateforme web Smart OSH
Développer des applications complètes reproduisant la fonctionnalité principale de Smart OSH
Remplacer l’accès normal des utilisateurs à la plateforme par un accès exclusif via l’API
Extraire en continu toute la base de données pour opérer en dehors de Smart OSH

Principes Généraux

L’API de Smart OSH est disponible pour tous nos clients sans limite établie de requêtes ou mises à jour, sous le principe d’utilisation « fair use » des ressources de la plateforme.

Authentification et gestion des sessions

L’authentification à l’API SmartOSH s’effectue via HTTP Basic Authentication. Lors du premier appel, le client doit s’authentifier avec les identifiants utilisateur API. Le client HTTP conservera le token résultant du HTTP Authentication Challenge et les appels suivants seront automatiquement authentifiés.

Les identifiants d’accès (utilisateur et mot de passe) peuvent être créés par l’administrateur SmartOSH depuis la console d’administration de la plateforme.

Gestion des sessions

Lors de l’utilisation de Basic Authentication, il est nécessaire que le client API maintienne la session entre les appels. Deux méthodes équivalentes existent :

Cookies de session : Le client HTTP conserve automatiquement les cookies reçues lors du premier appel.
Header x-session : Le client capture la valeur du header x-session reçue dans la première réponse et la renvoie dans tous les appels suivants.

Si la session n’est pas maintenue correctement :

Les appels seront extrêmement lents
La performance de l’abonnement client peut être compromise
La limite de sessions simultanées sera atteinte

Limite de sessions

L’API a une limite de 50 identifiants de session distincts par utilisateur par heure. Lorsque cette limite est dépassée, le service rejette les requêtes avec le message :

“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 courantes d’excès de sessions :

Le même utilisateur API est partagé par plusieurs utilisateurs ou systèmes réels
Les identifiants de session ne sont pas correctement conservés entre les appels
Les cookies de session ne sont pas réutilisées

Recommandations :

Maintenir la session active correctement via cookies ou en-têtes x-session
Si plusieurs systèmes ont besoin d’accès simultané, répartir les requêtes entre différents utilisateurs API
Vérifier que le client HTTP est configuré pour préserver les cookies entre les appels

Usage attendu

Mises à jour des données

L’API est conçue pour recevoir uniquement les données ayant subi des changements réels. Les clients doivent :

Envoyer des mises à jour uniquement lorsque l’information a effectivement changé
Implémenter une logique de détection de changements avant d’effectuer des appels à l’API
NE PAS envoyer des mises à jour répétitives des mêmes informations sans modifications

Limites techniques de vitesse (Rate Limiting)

Bien qu’il n’existe pas de limite stricte de volume total, Smart OSH met en place des contrôles de vitesse pour garantir la stabilité du service :

Limite maximale : 3 600 requêtes par heure (équivalent à 60 requêtes par minute)
Appels concurrents : 1. Les appels parallèles recevront un code status 429
Mécanisme de protection : Lorsque le système détecte un rythme supérieur à ces valeurs, un mécanisme de throttling s’active automatiquement pour limiter temporairement les requêtes

Codes de réponse et gestion des erreurs

Codes HTTP pertinents

Code	Signification	Action requise
`200 OK`	Requête réussie	Continuer normalement
`400 Bad Request`	Habituellement “You are using too many sessions”	Voir gestion des sessions
`401 Unauthorized`	Identifiants invalides ou session expirée	Vérifier les identifiants et se réauthentifier
`429 Too Many Requests`	Limite de vitesse dépassée	Implémenter backoff et réessayer
`503 Service Unavailable`	Service temporairement indisponible	Réessayer avec stratégie exponentielle
`504 / 524 Gateway Timeout`	Timeout dû à un blocage de ressources	Réessayer après un intervalle

Maintenance programmée

Smart OSH effectue des maintenances périodiques pouvant entraîner un code 503 Service Unavailable. Les fenêtres de maintenance sont notifiées à l’avance. Les clients doivent implémenter des stratégies de réessai face aux codes 503 pour gérer ces périodes sans perte de données.

Blocages dus à des opérations concurrentes

La plateforme peut retenir ou bloquer temporairement l’accès à certaines données lorsque :

Des opérations massives sont en cours (importations, processus batch, etc.)
D’autres utilisateurs effectuent des opérations individuelles sur les mêmes ressources
Des processus de calcul intensifs sont en cours

Pendant ces blocages, l’API peut subir des temps de réponse plus longs ou renvoyer des codes 503 / 504 / 524. Le client doit implémenter des réessais avec intervalles croissants.

Stratégies de réessai recommandées

Backoff exponentiel avec jitter :

Réessai 1 : attendre 1–2 secondes
Réessai 2 : attendre 2–4 secondes
Réessai 3 : attendre 30–60 secondes
Réessai 4 : attendre 180–300 secondes

Codes nécessitant un réessai : 429, 503, 504, 524, erreurs réseau/timeout.

Codes NE devant PAS être réessayés automatiquement : 400, 401, 403, 404, 422.

Bonnes pratiques

Requêtes en bloc avec pagination — Utiliser des endpoints de requêtes massives pour de grands volumes. Taille de page recommandée : 100–500 enregistrements.
Stratégies de backoff — Implémenter un recul exponentiel face aux erreurs ou réponses 429 / >500. Ajouter un jitter aléatoire pour éviter la synchronisation des réessais.
Détection locale des changements — Maintenir un registre de l’état des données dans le système client. Considérer l’usage de timestamps, checksums ou hashes pour détecter les changements.
Consolidation des mises à jour — Grouper plusieurs changements en une seule requête lorsque l’API le permet. Utiliser des opérations batch quand disponibles.
Timeouts appropriés — Connexion : 10–30 secondes. Lecture : 60–100 secondes pour opérations complexes.

Headers informatifs

L’API peut inclure les headers suivants pour monitorer l’usage :

x-throttled — Indique si les requêtes sont limitées par le serveur
x-requestsUserMinCount — Compteur des requêtes effectuées dans les 60 dernières secondes

Horaires recommandés

Pour les opérations massives, éviter autant que possible les heures de pointe :

Éviter : 9h00–18h00 (CET)
Préférer : 20h00–7h00 (CET) pour les chargements massifs
Coordonner avec le support pour opérations extraordinaires

Chargements massifs via Excel (KB020)

Objectif

Les outils de chargement massif via fichiers Excel (KB020) sont conçus pour :

Migrations initiales de données lors de la mise en place de SmartOSH
Mises à jour massives ponctuelles en cas de changements significatifs des données
Chargements incrémentaux de nouveaux enregistrements ou modifications d’enregistrements existants
Corrections massives de données suite à des incidents identifiés

Principe d’usage incrémental

Les chargements via KB020 doivent suivre un modèle incrémental, non de remplacement total :

Charger uniquement les enregistrements ayant changé depuis le dernier chargement
Inclure seulement les colonnes avec valeurs modifiées lorsque possible
NE PAS recharger massivement toute la base de données périodiquement
NE PAS uploader des fichiers avec des données identiques à celles déjà existantes sur la plateforme
NE PAS utiliser KB020 comme méthode habituelle de mise à jour des données changeant fréquemment

Impact des chargements massifs

Comme avec l’API, chaque chargement de données via KB020 déclenche validations, recalculs automatiques, notifications par email, activation de flux de travail et blocages temporaires de ressources.

Les chargements répétitifs de données sans changements génèrent des coûts informatiques inutiles, saturent les utilisateurs de notifications superflues et peuvent affecter la performance générale de l’environnement client.

Usage inapproprié de KB020

Les outils de chargement massif ne doivent pas être utilisés pour :

Remplacer les fonctionnalités de mise à jour des données disponibles dans l’interface web
Effectuer des rechargements systématiques et périodiques de la totalité des données sans modifications effectives
Mettre à jour des enregistrements dont les valeurs n’ont pas changé
Constituer la méthode principale de gestion et maintenance des données en remplacement de l’usage normal de la plateforme

Bonnes pratiques pour chargements en lot

Préparation du fichier Excel :

Identifier quels enregistrements ont réellement changé depuis le dernier chargement
Exporter depuis SmartOSH l’état actuel si une comparaison est nécessaire
Inclure uniquement les enregistrements modifiés ou nouveaux avec leurs colonnes identifiantes (ID, Key, code unique, etc.)

Fréquence recommandée :

Migrations initiales : une seule fois lors de la mise en place
Mises à jour normales : uniquement en cas de changements significatifs justifiant l’opération
Fréquence maximale recommandée : un chargement par jour
Pour mises à jour fréquentes, urgentes ou unitaires : utiliser l’API plutôt que KB020

Signes d’usage inapproprié :

Chargements quotidiens ou plusieurs fois par semaine des mêmes données
Fichiers avec des milliers d’enregistrements mais peu de changements réels
Chargements automatiques programmés sans validation préalable des changements générant beaucoup d’erreurs

Intervention en cas d’usage abusif

Smartosh se réserve le droit de contacter les clients dont le modèle d’usage :

Dépasse systématiquement les limites de vitesse établies
Génère des chargements inutiles via mises à jour répétitives sans changements
Compromet la performance générale de la plateforme
N’implémente pas de stratégies de réessai adéquates

Dans ces cas, nous travaillerons avec le client pour optimiser son intégration et garantir un usage durable du service. SmartOSH se réserve le droit de limiter ou restreindre l’usage de l’API.

Disponibilité et SLA

Disponibilité cible : 99,5 % (hors maintenances programmées et blocages fonctionnels des données propres à l’environnement client)
Support technique : Disponible en heures ouvrables