Intégrations — connecter Sphère à votre système d'information

Où trouver les intégrations ? #

Ouvrez Paramètres → Monitoring → Intégrations. La page s'intitule Intégrations et son sous-titre annonce son rôle : « Répercutez les événements de Sphère dans votre système d'information ».

L'accès est réservé aux administrateurs de la sphère. Une personne sans ce niveau voit un message qui l'invite à se rapprocher de l'administrateur de son organisation.

Tant qu'aucune intégration n'existe, la page propose trois départs courants pour se lancer : Contact créé → ERP, Ticket résolu → Helpdesk, Utilisateur créé → Annuaire RH.

Que montre la liste des intégrations ? #

Chaque ligne résume une intégration :

• Intégration — le nom que vous lui avez donné.
• Déclencheur — l'événement qui provoque l'appel (par exemple « Contact · Créé »).
• Authentification — la méthode employée : Aucune, Bearer, Clé d'API, Basic, éventuellement complétées d'une signature.
• Statut — Actif, Inactif ou En pause.
• Santé — 24 h — l'état de fonctionnement sur les dernières 24 heures : Saine, En échec, En pause, Jamais appelée ou Sans réponse, accompagné d'une petite courbe des livraisons heure par heure.

Une barre de recherche filtre par nom ou par adresse, et trois menus filtrent par entité, par statut et par santé. Réinitialiser les filtres revient à la vue complète.

Comment lire les indicateurs du haut de page ? #

Quatre compteurs résument l'état de vos intégrations :

• Intégrations actives — combien sont actives sur le total, avec la mention de celles qui sont inactives ou jamais appelées.
• Livraisons — 24 h — le nombre d'appels partis, comparé aux 24 heures précédentes.
• Taux de succès — 24 h — la part d'appels aboutis, avec le détail des échecs et des abandons.
• Demandent une action — le nombre d'intégrations en échec ou en pause. Quand il affiche « Rien à traiter », vous n'avez rien à faire.

Comment créer une intégration ? #

1. Ouvrez Paramètres → Monitoring → Intégrations.
2. Cliquez Nouvelle intégration.
3. Décrivez l'appel en une phrase : Quand un (entité) est (action) → appeler mon service, puis renseignez l'adresse, l'authentification et le corps envoyé. Le détail de l'éditeur est décrit dans Configurer une intégration (éditeur).
4. Cliquez Enregistrer.
5. Testez l'intégration avant de l'activer (voir la section suivante).
6. Activez-la depuis la section Activation de l'éditeur, ou depuis le menu de la ligne dans la liste.

💡 L'enregistrement et l'activation sont deux gestes distincts. Une intégration enregistrée mais inactive n'envoie rien : c'est voulu, cela vous laisse le temps de la tester.

Comment tester une intégration sans rien enregistrer ? #

Le test à blanc envoie un vrai appel à votre service, mais rien n'est enregistré côté Sphère : le test n'apparaît pas dans le journal des livraisons et ne compte dans aucun indicateur.

1. Ouvrez l'intégration, section Tester avant d'activer.
2. Cliquez Envoyer un test. (L'intégration doit être enregistrée au préalable : le test emploie la configuration enregistrée.)
3. Lisez le verdict, qui distingue nettement quatre cas :
   • Test réussi — votre service a accepté l'appel ; le code de réponse et le temps de réponse sont affichés. Vous pouvez activer l'intégration.
   • Rien n'a été envoyé — adresse refusée — l'adresse configurée n'est pas joignable depuis Internet ; l'appel a été arrêté avant l'envoi. Publiez votre service sur un domaine public en HTTPS.
   • Injoignable — aucune réponse — la requête est partie, votre serveur n'a pas répondu. Vérifiez qu'il tourne, que votre pare-feu accepte les appels et que le certificat est valide.
   • Votre service a répondu une erreur — la requête est partie et a été refusée. Vérifiez le chemin appelé, l'authentification attendue et le format du corps.

Chaque verdict s'accompagne d'une ligne À corriger ou À vérifier, et le bouton Voir la requête envoyée montre exactement ce qui est parti. Les valeurs sensibles y sont masquées : Sphère ne les réaffiche jamais en clair.

⚠️ Les tests sont limités en fréquence. Si le message « Trop de tests d'affilée » s'affiche, patientez le nombre de secondes indiqué.

Comment activer, désactiver ou supprimer une intégration ? #

Depuis le menu Plus d'actions d'une ligne de la liste, ou depuis l'éditeur :

• Activer — chaque événement correspondant déclenche désormais un appel.
• Désactiver — les appels cessent immédiatement. Rien n'est supprimé : la configuration et le journal des livraisons restent intacts, et vous pouvez réactiver à tout moment.
• Dupliquer — crée une copie nommée « … (copie) », inactive, sans secret ni historique. Pratique pour décliner une intégration existante vers une autre adresse.
• Supprimer — les appels cessent et l'historique des livraisons est effacé définitivement. La confirmation vous indique combien de livraisons sont enregistrées et depuis quand. Pour interrompre temporairement, désactivez plutôt.

Que veut dire « en pause » sur une intégration ? #

Quand votre service échoue plusieurs fois d'affilée, Sphère met l'intégration en pause automatiquement pour ne pas continuer à appeler dans le vide. Un bandeau l'annonce : « … a été désactivée automatiquement après N échecs consécutifs », avec la dernière erreur rencontrée et le moment où elle s'est produite.

Ce bandeau apparaît sur la vue d'ensemble et dans l'éditeur, là où vous venez réparer. Il propose deux raccourcis : Remplacer le jeton et Tester à nouveau.

Les livraisons de la période sont conservées et rejouables une fois le problème corrigé. Quand vous réactivez l'intégration, le compteur d'échecs est remis à zéro.

Comment savoir pourquoi une intégration échoue ? #

Le bloc Pourquoi ça échoue — 24 h regroupe les échecs par cause, avec pour chacune la correction attendue. Par exemple :

• Requête refusée — votre service refuse l'appel. Vérifiez le jeton, les en-têtes et le corps envoyé. Ce cas n'est pas réessayé automatiquement.
• Erreur du destinataire — votre service répond, mais quelque chose derrière lui est indisponible. Réessayé automatiquement.
• Délai dépassé — aucune réponse dans le temps imparti. Abandonnée une fois les tentatives épuisées, puis rejouable.
• Domaine introuvable, Certificat refusé, Connexion refusée — l'adresse ou le certificat de votre service posent problème.
• Adresse interdite — l'adresse est privée ou réservée. Sphère n'appelle que des adresses publiques en HTTPS.
• Corps invalide — le corps n'a pas pu être composé. Vérifiez le gabarit et les champs insérés.

Un clic sur un groupe ouvre le journal des livraisons filtré sur ce motif exact, avec la fenêtre de temps appliquée affichée. Voir Journal des livraisons d'une intégration.