Dépannage du connecteur¶

En bref

Cette page regroupe les symptômes les plus fréquents et la marche à suivre. Avant toute chose : relevez l'identifiant de corrélation renvoyé par l'API en cas d'erreur, et activez les journaux — ce sont les deux éléments que le support demandera.

Réflexes de diagnostic¶

État du service : écran Accueil de l'outil de configuration, ou console des services Windows (ServeurSensaas).
Journaux du connecteur : C:\ProgramData\Sage\SenSaaS\logs\Log.SenSaaS.txt par défaut.
Journal d'installation : SenSaaS.Updater.log, dans le dossier d'installation.
Tests intégrés : l'écran Dossiers Sage propose Tester la connexion (SQL) et Tester la connexion Sage (objets métiers) ; l'écran Données SenSaaS teste la base SenSaaS.
Observateur d'événements Windows si le service ne démarre pas du tout.

Le service ne démarre pas¶

Cause probable	Ce que vous constatez	Correctif
Certificat HTTPS absent	L'outil de configuration a signalé « Le certificat .pfx est introuvable » lors de l'application de la configuration	Écran Serveur Web › Générer le certificat, puis redémarrer le service
Port déjà utilisé	Le service s'arrête aussitôt après le démarrage	Vérifier qu'aucun autre service n'écoute sur le port choisi (443 par défaut), ou changer le port dans l'écran Serveur Web
Composants .NET manquants	Le service ne démarre pas après une installation manuelle des binaires	Relancer l'installeur : il installe les composants .NET 9 en version x86 requis
Aucune écoute activée	L'outil refuse d'enregistrer : « Au moins une écoute doit être activée »	Activer HTTP, HTTPS ou EasyConnect dans l'écran Serveur Web
Fichiers verrouillés après mise à jour	L'installeur affiche « Des fichiers de … sont toujours verrouillés »	Arrêter manuellement le service `ServeurSensaas`, puis relancer l'installeur

Le service démarre mais l'API ne répond pas

Vérifiez le pare-feu de la machine, l'adresse IP d'écoute (* pour toutes les interfaces) et le champ Hôtes autorisés de l'écran Serveur Web : un hôte non listé fait rejeter la requête.

`BadImageFormatException`¶

C'est l'erreur d'architecture par excellence : un composant 64 bits tente de charger les binaires Sage, qui sont 32 bits.

Le connecteur et l'outil de configuration sont livrés en x86 : c'est voulu et obligatoire.
N'essayez pas de relancer SenSaaS.Serveur.exe depuis un environnement 64 bits, ni de recompiler en « Any CPU ».
Si l'erreur survient après une intervention manuelle sur le dossier d'installation, réinstallez proprement avec l'installeur.

Sage introuvable ou connexion refusée¶

L'écran Dossiers Sage, bouton Tester la connexion Sage, donne le message exact.

Message	Cause	Correctif
« Aucun fichier Sage valide : sélectionnez le fichier GCM (ou MAE) du dossier. »	Les chemins des fichiers du dossier Sage ne sont pas renseignés ou n'existent pas	Renseigner les fichiers de la gestion commerciale et de la comptabilité
« Connexion refusée par Sage : vérifiez l'utilisateur et les mots de passe. »	Identifiants Sage erronés	Corriger l'utilisateur et les mots de passe, en distinguant gestion commerciale et comptabilité
« Échec : … » suivi d'un message Sage	Message remonté par Sage (mot de passe refusé, dossier verrouillé, version incompatible…)	Traiter le message Sage lui-même

Autres causes à écarter :

Sage 100c n'est pas installé sur la machine du connecteur : c'est un prérequis, les objets métiers sont chargés dans le processus du connecteur.
Version de Sage non prise en charge : les versions couvertes vont de la version 7 à la version 12.
Le compte du service n'a pas accès aux fichiers du dossier Sage : vérifiez les droits sur le répertoire du dossier Sage.

Un seul dossier Sage à la fois

Le connecteur n'ouvre qu'un dossier Sage à la fois dans son processus, et les opérations sur les objets métiers sont exécutées les unes après les autres. Sur un appel qui interroge plusieurs dossiers, la réponse peut donc être plus lente qu'attendu : ce n'est pas un incident.

Problèmes de base de données¶

Base SenSaaS injoignable¶

Symptômes : dans l'outil de configuration, les listes d'utilisateurs, de dossiers ou d'accès B2B restent vides, avec un message d'erreur en bas d'écran ; les compteurs de la barre latérale disparaissent.

Écran Données SenSaaS › Tester la connexion.
Le message « Échec de connexion : … » reprend l'erreur SQL Server telle quelle : traitez-la (instance introuvable, base inexistante, authentification refusée…).
Si vous laissez l'utilisateur et le mot de passe vides, la connexion se fait en sécurité intégrée : c'est le compte du service qui doit alors disposer des droits SQL, pas votre compte Windows.

Base Sage injoignable¶

Même méthode depuis l'écran Dossiers Sage, bouton Tester la connexion. Ce test est indépendant des objets métiers Sage : s'il passe alors que le test Sage échoue, le problème est côté identifiants Sage, pas côté SQL.

Erreurs renvoyées par l'API¶

Les erreurs de l'API v2 arrivent au format ProblemDetails : un objet JSON qui porte un status HTTP, un title, un detail, un code propre à SenSaaS et un correlationId. Le code est la clé du diagnostic.

Situation	Statut	Ce qu'il faut faire
Jeton absent, invalide ou expiré	401	Le jeton d'accès dure 20 minutes : rafraîchissez-le ou reconnectez-vous
Dossier non autorisé pour cet utilisateur	403 (`DOSSIER.NOT_AUTHORIZED`)	Accorder le dossier à l'utilisateur dans Accès et droits
Plusieurs dossiers visés par une écriture	400 (`DOSSIER.AMBIGUOUS`)	Une écriture ne cible qu'un seul dossier : préciser `targets`
Écritures v2 désactivées	503 (`SAGE.COM.UNAVAILABLE`)	Activer Autoriser les écritures API v2 dans l'écran Serveur Web, puis redémarrer le service
Objet Sage en lecture seule	409 (`SAGE.READONLY`)	L'objet visé ne peut pas être écrit par cette voie
Corps de requête vide ou invalide	400 (`VALIDATION.MODEL`)	Corriger le corps de la requête
Objet introuvable dans Sage	404 (`SAGE.NOT_FOUND`)	Vérifier la clé demandée et le dossier ciblé
Trop de tentatives de connexion	429	La limite est de 30 requêtes par minute et par adresse IP sur l'authentification : espacer les appels

Derrière un proxy inverse, la limitation de débit peut bloquer tout le monde

Si toutes les requêtes se présentent avec l'adresse du proxy, elles partagent le même compteur. Déclarez le proxy dans Proxys de confiance (écran Serveur Web) pour que l'adresse réelle du client soit prise en compte. Voir Sécurité.

Toujours transmettre l'identifiant de corrélation¶

Cet identifiant est renvoyé dans l'en-tête X-Correlation-Id de chaque réponse et dans le corps des erreurs. Il permet de retrouver, dans les journaux du connecteur, les deux lignes qui encadrent l'appel fautif — méthode, chemin, durée, utilisateur et exception.

Problèmes d'impression PDF¶

Les messages « Le dossier des modèles n'est pas configuré pour ce dossier », « Modèle non trouvé pour ce type de document » et les erreurs de compilation d'un modèle sont traités dans Modèles d'impression.

Problèmes de licence¶

Symptôme	Piste
« Licence non lisible » ou « Non vérifiée »	Aucune licence en ligne ni fichier exploitable : voir Licence
Provenance « Hors-ligne (cache signé) » qui persiste	Le portail n'est pas joignable depuis la machine : vérifier la sortie Internet
« Licence expirée »	Le service continue de fonctionner mais les modules sont désactivés : renouveler la licence sur le portail
Accès B2B refusés	Quota de la licence atteint : voir le compteur de l'écran Accès B2B

Accès à l'outil de configuration¶

Symptôme	Correctif
« Mot de passe incorrect. »	Ressaisir ; en cas d'oubli, voir la procédure de récupération dans Se connecter à l'outil
Le pilotage du service échoue avec un message de droits	Relancer l'outil en tant qu'administrateur (il demande normalement l'élévation au lancement)
L'état du service reste « Indéterminé »	Le service n'est pas installé sur cette machine, ou le compte courant n'a pas le droit de l'interroger

Quand contacter le support¶

Rassemblez au préalable :

la version du connecteur (écran Accueil, section Composants installés) ;
l'identifiant de corrélation de l'appel fautif, ou l'heure précise de l'incident ;
le fichier de journal couvrant cette période, avec le niveau Debug si possible ;
le message exact affiché, et le dossier Sage concerné.