Configurer une connexion Web Service
Déclarer une API externe, choisir son authentification, la tester et comprendre ce que sa suppression casse
À quoi ça sert
Une connexion Web Service déclare une API externe que le CRM peut interroger : l'adresse du service et la façon de s'y authentifier. Une fois la connexion créée, vous l'utilisez sur des champs de type « Web Service » ou « Source Web Service », qui affichent sur la fiche des données venues de ce service — un solde de fidélité, un historique de réservations, un état d'abonnement.
L'écran se trouve dans « CRM », « Administration », carte « Connexions Web Service ». Il est réservé aux administrateurs du module CRM.
La page propose aussi un « Catalogue » d'API publiques gratuites, activables en un clic, sans clé ni jeton.
Le paramétrage des champs qui consomment ces connexions est décrit dans Champs Web Service.
Concepts clés
- Connexion — un nom, une URL de base et un mode d'authentification.
- URL de base — l'adresse racine du service. Les chemins configurés sur les champs s'ajoutent à cette adresse.
- Type d'authentification — la façon dont le CRM prouve son identité au service.
- Valeur d'authentification — la clé ou le jeton. Elle est chiffrée et n'est plus affichée après enregistrement.
- Headers supplémentaires — des en-têtes personnalisés envoyés à chaque requête.
- Catalogue — une liste d'API publiques prêtes à l'emploi, affichée au-dessus du tableau des connexions. Chaque entrée devient une connexion en un clic.
- Modèle de endpoint — un endpoint et ses mappings de données déjà écrits pour une entrée du catalogue, proposés sur le champ « Web Service » par « Partir d'un modèle ».
- Connexion active — une connexion inactive cesse de rapporter des données aux champs qui l'utilisent, exactement comme si elle avait été supprimée.
Comment faire
Créer une connexion
- Ouvrez « CRM », « Administration », puis « Connexions Web Service ».
- Cliquez sur « Nouvelle connexion ». Un volet s'ouvre sur la droite.
- Saisissez le « Nom », par exemple « API Clients ».
- Saisissez l'« URL de base », par exemple
https://api.example.com. - Choisissez le « Type d'authentification » et complétez les champs qui apparaissent.
- Renseignez la « Valeur d'authentification » si le type en demande une.
- Ajoutez les « Headers supplémentaires » nécessaires avec « Ajouter un header ».
- Laissez « Active » activé, puis cliquez sur « Enregistrer ».
Le message « Connexion créée avec succès » s'affiche et la connexion apparaît dans le tableau.
Activer une API du catalogue
- Ouvrez « CRM », « Administration », puis « Connexions Web Service ».
- Dans la section « Catalogue », repérez la carte de l'API voulue. Le lien « Documentation » ouvre sa documentation officielle dans un nouvel onglet.
- Cliquez sur « Activer ».
Le message « Connexion activée » s'affiche, la carte porte le badge « Activée » et la connexion apparaît dans le tableau, active et sans authentification. Elle se modifie, se teste et se supprime comme une autre connexion.
Partir d'un modèle sur un champ « Web Service »
- Ouvrez l'entité, onglet « Propriétés », puis le champ « Web Service » (ou créez-le).
- Dans l'onglet « Configuration », choisissez dans « Connexion » une connexion issue du catalogue.
- Sous « Endpoints », cliquez sur « Partir d'un modèle ».
- Si l'API propose plusieurs modèles, choisissez-en un dans « Modèle ».
- Pour chaque entrée demandée (« Variable pour : SIREN ou SIRET », par exemple), choisissez le champ de la fiche qui la fournit.
- Cliquez sur « Appliquer ».
Un endpoint est ajouté avec son chemin, ses paramètres de requête et ses mappings de données. Vous pouvez tout ajuster avant d'enregistrer le champ. Le bouton « Partir d'un modèle » n'apparaît que si la connexion choisie vient du catalogue.
Tester une connexion
- Ouvrez la connexion, ou restez dans le volet de création.
- Cliquez sur « Tester ».
- Dans la fenêtre qui s'ouvre, saisissez le « Chemin de test » à interroger,
/par défaut. - Cliquez sur « Tester ».
Le message « Connexion réussie » s'affiche en cas de succès, « Échec de la connexion » suivi du message renvoyé par le service sinon.
En modification, laisser la « Valeur d'authentification » vide fait reprendre le secret déjà enregistré : il n'est pas nécessaire de le ressaisir pour tester.
Modifier une connexion
- Ouvrez « Connexions Web Service » et cliquez sur la ligne de la connexion.
- Modifiez les valeurs voulues. Le bouton « Enregistrer » s'active dès qu'une valeur change.
- Cliquez sur « Enregistrer ».
Le message « Connexion mise à jour avec succès » s'affiche.
Consulter l'historique d'une connexion
- Ouvrez la connexion.
- Cliquez sur l'icône « Historique » dans l'en-tête du volet.
Les changements sont listés du plus récent au plus ancien, avec leur date et l'auteur : « Connexion créée », « Connexion mise à jour », « Connexion supprimée ».
Désactiver une connexion
- Ouvrez la connexion.
- Désactivez « Active », puis cliquez sur « Enregistrer ».
La connexion reste déclarée, mais les champs qui s'appuient dessus cessent de rapporter des données.
Supprimer une connexion
- Ouvrez la connexion.
- Cliquez sur « Supprimer », en bas à gauche du volet.
- Lisez l'avertissement, puis confirmez par « Supprimer ».
Le dialogue demande « Supprimer cette connexion ? » et prévient : « Les champs Web Service utilisant cette connexion ne pourront plus récupérer de données. » Vérifiez donc, avant de supprimer, quels champs s'appuient sur la connexion : ils resteront en place mais n'afficheront plus rien.
Référence
Champs de la connexion
| Champ | Obligatoire | Remarque |
|---|---|---|
| Nom | Oui | Sert à identifier la connexion dans les champs |
| URL de base | Oui | Doit être une adresse valide |
| Type d'authentification | Oui | « Aucune » par défaut |
| Valeur d'authentification | Selon le type | Chiffrée, jamais réaffichée |
| Headers supplémentaires | Non | Envoyés à chaque requête |
| Active | Non, activée par défaut | Une connexion inactive ne rapporte plus rien |
Les six types d'authentification
| Type | Champs de configuration |
|---|---|
| Aucune | Aucun |
| Clé API | Nom du header, valeur d'authentification |
| Bearer Token | Valeur d'authentification |
| Basic Auth | Valeur d'authentification |
| OAuth2 Client Credentials | URL du token, Client ID, Scope, valeur d'authentification |
| Visor (mTLS + auth applicative) | Certificat client, clé privée, autorité de certification, passphrase, et éventuellement identifiants applicatifs |
Le type « Visor » vise un système externe précis. Il demande le contenu des
fichiers de certificat au format PEM, stockés chiffrés, et propose en plus une
« Authentification applicative Visor » à activer si le service est en mode
sécurisé : nom d'utilisateur, mot de passe et « Timeout de session (secondes) »,
10 secondes par défaut. Une aide dans le formulaire rappelle les précautions à
prendre, notamment l'ajout d'un header RequestFormat=JSON.
Boutons de test selon le type
| Type | Boutons proposés |
|---|---|
| Tous sauf Visor | « Tester » |
| Visor | « Tester (mTLS seul) » et « Tester avec auth applicative » |
« Tester (mTLS seul) » interroge le chemin que vous saisissez, sans l'authentification applicative. « Tester avec auth applicative » interroge un chemin de vérification imposé et ignore le « Chemin de test » saisi.
Le catalogue
| API | Ce qu'elle apporte | Modèles proposés |
|---|---|---|
| API Recherche d’entreprises | Raison sociale, siège, code NAF, forme juridique et effectif d'une entreprise à partir de son SIREN ou SIRET | « Entreprise par SIREN / SIRET » |
| Géocodage IGN (Géoplateforme) | Adresse normalisée et coordonnées GPS à partir d'une adresse saisie librement | « Adresse normalisée » |
| API Découpage administratif | Commune, département et région à partir d'un code postal | « Commune par code postal » |
| VIES — TVA intracommunautaire | Validité d'un numéro de TVA intracommunautaire, avec la raison sociale et l'adresse déclarées | « Validation du numéro de TVA » |
| BODACC — annonces légales | Procédures collectives (redressement, liquidation) publiées au BODACC pour un SIREN | « Procédures collectives par SIREN » |
Une API du catalogue ne s'active qu'une fois : à la seconde tentative, le message « Cette connexion du catalogue est déjà activée. » s'affiche, et le bouton est remplacé par le badge « Activée ».
Le tableau des connexions
Colonnes : « Nom », « URL de base », « Type d'authentification », « Statut » (Active ou Inactive). Sans connexion : « Aucune connexion configurée ».
Où les connexions sont utilisées
| Type de champ | Ce qu'il fait |
|---|---|
| Web Service | Affiche sur la fiche des données lues sur le service |
| Source Web Service | Déclare une source de données réutilisable par d'autres champs |
Les deux exigent qu'une connexion soit choisie ; à défaut, le champ ne peut pas être enregistré. Le sélecteur de connexion propose aussi les connexions inactives : vérifiez le statut avant de choisir.
Messages
| Message | Situation |
|---|---|
| « Connexion créée avec succès » | Création réussie |
| « Connexion mise à jour avec succès » | Modification réussie |
| « Connexion supprimée avec succès » | Suppression réussie |
| « Connexion réussie » | Test réussi |
| « Échec de la connexion » | Test échoué, suivi du message du service |
| « Connexion activée » | Activation d'une API du catalogue réussie |
| « Connexion Web Service introuvable » | La connexion n'existe plus |
Questions fréquentes
Puis-je revoir la clé ou le jeton après l'avoir enregistré ? Non : « Cette valeur est chiffrée et ne sera plus visible après enregistrement. » Pour en changer, saisissez la nouvelle valeur et enregistrez.
Que se passe-t-il pour les champs si je supprime la connexion ? Ils restent en place mais n'affichent plus rien : « Les champs Web Service utilisant cette connexion ne pourront plus récupérer de données. » Désactiver la connexion produit le même effet, de façon réversible.
Dois-je créer une clé pour les API du catalogue ? Non. Elles sont publiques : la connexion est créée sans authentification.
Puis-je utiliser la même connexion sur plusieurs entités ? Oui. Une connexion est déclarée une fois pour l'organisation et se choisit ensuite sur autant de champs que nécessaire.
Faut-il ressaisir le secret pour tester une connexion existante ? Non. Laissez « Valeur d'authentification » vide : le test reprend le secret déjà enregistré.