Gestion de Session et Profils

Ce guide explique comment connecter HtkDoli à votre ERP Dolibarr, et comment gérer vos différentes sessions (profils) en toute sécurité.

Dans HtkDoli, chaque connexion à une instance Dolibarr est enregistrée sous forme de session (aussi appelée profil). Vous pouvez créer autant de sessions que nécessaire — une par société, par instance ou par utilisateur — et basculer de l'une à l'autre depuis l'écran d'accueil « Espace sessions ».

Connexion à votre instance Dolibarr

La connexion à Dolibarr se fait exclusivement au moyen d'une clé API. HtkDoli ne demande pas de mot de passe : il n'y a pas de connexion par identifiant et mot de passe.

Pour créer une session, trois informations sont obligatoires :

Nom du profil : le nom affiché dans la liste des sessions et sur le tableau de bord (par exemple : Mon Association).
URL Dolibarr : l'adresse complète de votre instance (par exemple : https://mondoli.exemple.com).
Clé API : la clé générée dans Dolibarr pour votre utilisateur.

Où trouver votre clé API ? Dans Dolibarr : Avatar → Fiche → Clé pour API.

Champs optionnels

Identifiant : votre nom d'utilisateur Dolibarr. Ce champ est purement informatif ; il n'est pas utilisé pour s'authentifier (l'authentification repose uniquement sur la clé API).
Clé API Pappers : permet la recherche et l'auto-complétion des sociétés lors de la création de tiers.
Numéro d'entité : pour les installations Dolibarr multi-entités (module Multicompany). La valeur par défaut est 1.
Notes : un espace libre pour vos remarques personnelles.

Personnalisation de la session

Pour repérer vos sessions d'un coup d'œil, vous pouvez choisir une couleur et une icône métier (entreprise, comptable, technicien, direction, commercial, RH, etc.) pour chaque profil.

Créer une session — interface

À l'ouverture de l'application, l'écran « Espace sessions » s'affiche avec la liste de vos sessions existantes.
Appuyez sur le bouton + (ou sur « Créer une session » si la liste est vide).
Renseignez au minimum le Nom du profil, l'URL Dolibarr et la Clé API.
(Facultatif) Renseignez les champs optionnels, choisissez une couleur et une icône.
Appuyez sur Enregistrer.

Tant que les trois champs obligatoires ne sont pas remplis, le bouton Enregistrer reste inactif et les champs manquants sont signalés.

Tester la connexion et les autorisations

Depuis l'écran d'édition d'une session, deux outils vous aident à valider votre configuration :

Tester la connexion : vérifie que l'URL et la clé API permettent bien de joindre votre Dolibarr. ⚠️ Si votre instance utilise http:// (non sécurisé) au lieu de https://, l'application vous en avertit explicitement.
Vérifier autorisations : analyse module par module les droits de votre utilisateur Dolibarr, pour identifier ce qui sera accessible (ou non) dans l'application.

Gestion Multi-Sessions et Profils

HtkDoli est conçu pour les utilisateurs gérant plusieurs entreprises ou travaillant avec plusieurs instances de Dolibarr.

Interface utilisateur

Liste des sessions : l'écran « Espace sessions » présente toutes vos sessions sous forme de cartes. Vous pouvez les rechercher (par nom ou URL) et les trier (par nom ou par date de dernière connexion).
Ouvrir / changer de session : appuyez sur la carte d'une session pour vous y connecter. Pour revenir à la liste et basculer vers une autre session, quittez la session en cours.
Ajouter une session : appuyez sur le bouton + pour créer une nouvelle session.
Modifier une session : appuyez sur l'action de modification d'une carte pour ouvrir l'éditeur (nom, URL, clé, couleur, icône, etc.).
Supprimer une session : vous pouvez supprimer une session devenue inutile. ⚠️ Cette suppression est définitive : elle efface le profil, sa clé API et toutes ses données locales.

Purger ou supprimer une session

Depuis l'éditeur d'une session existante, deux actions distinctes sont disponibles :

Purger cette session : supprime toutes les données locales (tiers, factures, commandes, etc.) mais conserve le profil et la clé API. Une nouvelle synchronisation sera nécessaire à la prochaine ouverture. Utile pour repartir d'un cache propre sans tout reconfigurer.
Supprimer cette session : supprime définitivement le profil, sa clé API (du trousseau) et l'ensemble de ses données locales.

Isolation stricte des données

La sécurité et la confidentialité sont au cœur de l'architecture de HtkDoli :

Clé API protégée : la clé API n'est jamais stockée en clair dans la base ; elle est conservée dans le trousseau (Keychain) sécurisé de l'appareil, accessible uniquement lorsque l'appareil est déverrouillé.
Bases de données séparées : chaque profil possède sa propre base de données SQLite locale (Profile_{UUID}.store), protégée par le chiffrement de fichiers du système.
Aucune fuite d'information : le cache réseau, les sessions, les cookies et les préférences (UserDefaults, App Group) sont strictement liés au profil actif et nettoyés lorsque vous quittez la session.
Clôture de session propre : lors du changement de profil ou de la déconnexion, les processus en arrière-plan (synchronisation, Live Activities, notifications planifiées, données du widget) liés au profil précédent sont explicitement arrêtés et purgés de la mémoire pour prévenir toute interférence.

Verrouillage par code PIN

Une session peut être protégée par un code PIN à 4 chiffres. Lorsque le verrouillage est actif, ce code est demandé pour accéder à la session, ajoutant une protection supplémentaire en cas d'accès non autorisé à l'appareil.

Ouverture d'une session et synchronisation initiale

Quand vous tapez sur un profil pour vous connecter :

Préparation (~1 seconde, parfois plus si le profil n'a jamais été ouvert sur cet appareil) : un voile « Ouverture de la session… » s'affiche pendant que l'app charge votre clé API et prépare la base de données locale.
Synchronisation initiale : l'app commence à récupérer vos données depuis votre Dolibarr (tiers, factures, commandes, etc.). Vous voyez l'avancement par module.
Entrée dans la session : dès que la sync a démarré, un bouton « Entrer (sync en arrière-plan) » apparaît en bas de l'écran. Tapez-le pour aller directement au tableau de bord sans attendre la fin — la sync continue toute seule en arrière-plan. Une fois la synchronisation terminée, le bouton devient « Entrer dans la session » (ou « Entrer (Mode Hors Ligne) » s'il n'y a pas de réseau).

Pendant la sync en arrière-plan

Une fois sur le tableau de bord, une petite bulle « Synchronisation en cours… » flotte en haut de l'écran tant que la sync n'est pas terminée. Vos listes (Tiers, Factures, etc.) se remplissent au fur et à mesure des téléchargements — vous pouvez les consulter dès maintenant, elles s'enrichiront automatiquement.

Quand la sync se termine :

La bulle disparaît
Un toast s'affiche : « Données à jour » (succès), « Terminée — mode hors ligne » (pas de réseau, vous travaillerez sur les données locales), ou « Terminée avec des erreurs » (en cas de souci).

Attendre la sync ou non ?

C'est à vous de voir :

Vous attendez (laisser l'écran de sync ouvert) si vous voulez voir le détail de chaque module qui se synchronise (logs, progression) — utile pour diagnostiquer.
Vous entrez tôt si vous savez ce que vous voulez consulter et n'avez pas besoin du détail. Le confort UX est meilleur.

Dans tous les cas, les données téléchargées sont les mêmes — c'est juste l'UI pendant l'attente qui change.

Permissions Dolibarr requises

Pour que la connexion et la synchronisation fonctionnent correctement, il est impératif que certaines permissions et configurations soient actives côté Dolibarr.

1. Activation de l'API REST

Votre instance Dolibarr doit avoir le module API/Web services REST activé.

Configuration : Connectez-vous à Dolibarr via un navigateur web, allez dans Configuration > Modules/Applications et activez le module "API REST".

2. Droits de l'utilisateur

L'utilisateur dont vous utilisez la clé API doit disposer des permissions appropriées dans Dolibarr pour interagir avec les modules.

Accès API : L'utilisateur doit avoir l'autorisation de consulter et d'utiliser les API.
Droits par module : Si vous n'avez pas le droit de voir les "Tiers" ou les "Factures" dans la configuration web de Dolibarr, l'API refusera l'accès, et ces données n'apparaîtront pas dans HtkDoli.
Création/Modification : Les actions de création, d'édition ou de suppression via l'application requièrent également les droits correspondants pour votre utilisateur dans Dolibarr.

Captures d'écran

4 captures — cliquez pour agrandir