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 vérifiez que les journaux sont actifs : ce sont les deux éléments que le support demandera.

Réflexes de diagnostic

1. État du service : écran Accueil de l'outil de configuration, ou console des services Windows (ServeurSensaas).
2. Journaux du connecteur : C:\ProgramData\Sage\SenSaaS\logs\Log.SenSaaS.txt par défaut.
3. Journal d'installation : SenSaaS.Updater.log, dans le dossier d'installation.
4. 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.
5. 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 (4000 en EasyConnect, 443 en HTTPS standard 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 10 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.

Le connecteur n'est pas joignable

Le portail SenSaaS vérifie à chaque synchronisation qu'il joint le connecteur, en appelant l'adresse /auth/ping, qui doit répondre pong.

Symptôme	Cause probable	Correctif
"délai dépassé" en EasyConnect	Client EasyConnect déconnecté, ou connecteur qui n'écoute pas sur l'adresse EasyConnect	Écran EasyConnect : vérifier le statut, Reconnecter ou Rejoindre le réseau, puis Vérifier l'accessibilité depuis l'Accueil
"Le connecteur SenSaaS ne répond pas sur le point local"	Service non démarré (configuration, certificat, port occupé)	Démarrer le service depuis l'Accueil, puis lire le journal
"Le réseau EasyConnect a refusé la demande d'adhésion."	Accès sortant au serveur EasyConnect bloqué	Ouvrir l'accès sortant, puis réessayer
"connexion impossible" en mode port	Port non ouvert ou non redirigé, adresse publique erronée	Ouvrir et rediriger le port, corriger l'adresse publique, ou revenir à EasyConnect
"réponse inattendue (HTTP )"	Un autre service répond sur ce port	Ouvrir https://<adresse>:<port>/auth/ping dans un navigateur : il doit afficher pong ; sinon libérer ou changer le port
Encadré "Configuration de l'accessibilité à finaliser" sur l'Accueil	L'étape Accessibilité de l'assistant a été passée malgré l'échec du test	Corriger l'accès, puis Vérifier l'accessibilité : l'encadré disparaît quand le portail confirme

Les routes d'authentification et de vérification du serveur sont limitées à 30 requêtes par minute et par adresse IP. Un premier rattachement d'un grand nombre d'utilisateurs peut donc prendre environ une minute par tranche de trente.

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.

Toute l'API v2 répond 503

Code	Cause	Correctif
CONFIG.INCOMPLETE, avec le nom d'un fichier .dll dans le detail	Un composant du connecteur manque dans le dossier d'installation	Réinstaller ou mettre à jour le connecteur avec l'installeur ; aucune donnée n'est en cause
SAGE.COM.UNAVAILABLE sur une écriture	Écritures v2 désactivées dans l'outil (elles sont activées par défaut)	Activer Autoriser les écritures API v2 dans l'écran Serveur Web, partie Options, puis redémarrer le service
SAGE.COM.UNAVAILABLE sur une lecture	Connexion à Sage impossible	Voir la section suivante

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 100 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. Sur un lecteur réseau, l'écran Dossiers Sage propose de faire tourner le service sous le compte de l'utilisateur connecté.

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.

1. Écran Données SenSaaS › Tester la connexion.
2. Le message "Échec de connexion : …" reprend l'erreur SQL Server telle quelle : traitez-la (instance introuvable, base inexistante, authentification refusée…).
3. 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.

Connexion et droits

Code	Statut	Ce qu'il faut faire
AUTH.INVALID_TOKEN	401	Jeton absent, mal signé ou refusé : se reconnecter ; le detail donne le motif
AUTH.TOKEN_EXPIRED	401	Le jeton du connecteur dure 20 minutes : le renouveler, puis rejouer l'appel
AUTH.UTILISATEUR_INCONNU	403	Connexion par la webapp sans utilisateur actif du connecteur pour cet email : créer ou activer l'utilisateur dans Utilisateurs, avec la même adresse email
AUTH.FORBIDDEN	403	Droit retiré : opération de l'API (onglet API), document (onglet Documents, dont le droit Imprimer) ou écritures comptables. Le detail nomme le droit en cause ; voir Sécurité
DOSSIER.NOT_AUTHORIZED	403	Accorder le dossier à l'utilisateur dans Utilisateurs
(aucun code)	429	Trop de tentatives : 30 requêtes par minute et par adresse IP sur l'authentification, espacer les appels

Dossiers ciblés

Code	Statut	Ce qu'il faut faire
DOSSIER.AMBIGUOUS	400	Une écriture ne cible qu'un seul dossier : préciser targets
DOSSIER.REQUIRED	400	Écriture sans cible alors que l'utilisateur a plusieurs dossiers : préciser targets
DOSSIER.CONFLICT	400	Le corps de la requête désigne un dossier absent de ?targets= : aligner les deux, ou retirer la cible du corps
DOSSIER.UNKNOWN	404	Dossier inexistant dans la configuration du connecteur

Données et écritures

Code	Statut	Ce qu'il faut faire
VALIDATION.MODEL	400	Corriger le corps de la requête (vide, illisible, ou pièce comptable non équilibrée)
QUERY.INVALID	400	Requête /v2/query refusée : champ inconnu, table inconnue, syntaxe ou erreur SQL ; le detail localise l'anomalie
SAGE.NOT_FOUND	404	Vérifier la clé demandée et le dossier ciblé
SAGE.READONLY	409	L'objet ne peut pas être écrit par cette voie ; le detail et l'extension sageDetail indiquent la voie à utiliser
SAGE.IN_USE	409	Suppression d'un client ou d'un fournisseur qui porte des documents, lignes, écritures ou règlements : le detail donne les compteurs
SAGE.COM.PROCESS	422	Refus de Sage (écriture lettrée, période close, colonne non modifiable…) : lire sageDetail
(aucun code)	405	POST ou DELETE sur /v2/ecriture : saisir ou supprimer une écriture comptable par pièce équilibrée, sur /v2/ecriturepiece

Sur /v2/query, une colonne demandée qui n'existe pas dans un dossier n'est pas une erreur : elle est retirée du résultat et signalée par un avertissement QUERY.COLUMN_IGNORED dans meta.warnings.

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

Statut et code	Cause	Correctif
404 SAGE.NOT_FOUND	Pièce introuvable	Vérifier le type et le numéro du document
409 CONFIG.INCOMPLETE	Aucun PDF archivé, et dossier des modèles non renseigné, introuvable, ou modèle du type de document absent	Renseigner Modèles PDF du dossier dans l'écran Dossiers Sage, ou Préparer les modèles
422 PDF.GENERATION	Échec de génération du modèle (chargement, préparation, export)	Corriger le modèle ; le detail donne l'étape et le message
403 AUTH.FORBIDDEN	Droit Voir ou Imprimer retiré pour ce type ou ce statut de document	Ajuster l'onglet Documents de Filtres et accès

Le détail des modèles et des messages est dans Modèles d'impression.

Problèmes de licence

Symptôme	Piste
"Non vérifiée" juste après l'installation	Pas encore de jeton serveur : rendre le connecteur joignable, puis Synchroniser dans Utilisateurs
"Licence non valide"	Aucune licence active pour ce serveur sur le portail, ou jeton refusé : le code exact est dans le journal ; voir Licence
Provenance "Hors-ligne (cache signé)" qui persiste	Le portail n'est pas joignable depuis la machine : rétablir l'accès HTTPS sortant avant la date affichée
Licence renouvelée mais toujours "Licence expirée"	État conservé jusqu'à une heure : Actualiser la licence
"Licence expirée"	Le service continue de fonctionner mais les modules sont désactivés : renouveler la licence sur le portail
Cache ignoré après un changement d'heure	Horloge de la machine reculée de plus de 24 heures : corriger l'heure
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
Configuration illisible après un changement de machine	Le fichier est chiffré avec une clé propre à l'ancienne machine : importer un export JSON de la configuration, puis ressaisir les secrets (voir Sécurité)

Quand contacter le support

Rassemblez au préalable :

• la version du connecteur (écran Accueil, section Composants installés) et le code machine (écran Licence) ;
• 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, transmis par un canal privé ;
• le message exact affiché, et le dossier Sage concerné ;
• au besoin, l'export JSON de la configuration (les secrets y sont masqués).

Voir aussi

• Journalisation
• Sécurité
• Installer le connecteur
• Référence de l'API