Configurer une intégration (éditeur)

Comment choisir l'événement qui déclenche l'appel ? #

La section Déclencheur se lit comme une phrase à compléter : « Quand un … est … → appeler mon service. »

1. Choisissez l'entité : Contact, Organisation, Utilisateur ou Ticket.
2. Choisissez l'action : Créé, Modifié, Supprimé ou Statut modifié.

Les couples proposés sont ceux qui sont réellement branchés pour votre organisation : un couple qui n'apparaît pas dans les listes n'existe pas chez vous. Si les listes restent vides, réessayez dans un instant — le catalogue n'a pas pu être chargé.

💡 Le déclencheur commande tout le reste : les champs disponibles dans le corps en dépendent. Changez-le et les champs proposés changent aussi.

Comment indiquer l'adresse à appeler ? #

Dans la section qui décrit où Sphère envoie la requête :

1. Saisissez l'URL complète de votre service, par exemple https://exemple.tld/api/v2/customers.
2. Choisissez la méthode (le verbe HTTP). Un corps composé n'a de sens qu'avec un verbe qui en accepte un.
3. Choisissez le type de corps : JSON, urlencoded ou form-data.

L'adresse est vérifiée à la saisie et vous répond aussitôt :

• Adresse publique vérifiée — HTTPS, hors plages privées : tout va bien.
• Adresse non reconnue : il manque une URL complète, du type https://exemple.tld/hooks.
• Sphère n'appelle que des adresses en HTTPS : le http:// simple est refusé.
• Adresse privée — Sphère ne peut pas l'appeler : votre service doit être joignable depuis Internet, éventuellement via votre serveur relais.

Comment authentifier Sphère auprès de mon service ? #

La section Authentification distingue deux mécanismes aux rôles opposés :

• Jeton — Sphère s'authentifie chez vous. Choisissez la méthode (Bearer, Basic, clé d'API…), puis saisissez le jeton, ou l'identifiant et le mot de passe, ou le nom de l'en-tête et sa valeur.
• Signature — vous vérifiez que l'appel vient bien de Sphère. Chaque appel porte alors un en-tête de signature que votre service recalcule pour s'assurer de l'origine du message.

Trois règles à connaître :

1. Les valeurs sont enregistrées chiffrées et jamais réaffichées. Laisser un champ vide conserve la valeur actuelle : un champ vide n'est pas une perte.
2. Changer de méthode remet les identifiants à zéro. Saisissez les nouveaux ; laissés vides, l'authentification est retirée à l'enregistrement.
3. Le secret de signature ne s'affiche qu'une seule fois, à sa création (Révéler une fois). Notez-le immédiatement : ni un rechargement de page ni aucune autre manœuvre ne le rendra.

Comment renouveler le secret de signature ? #

1. Ouvrez l'intégration, section Authentification, bloc Signature.
2. Cliquez Renouveler, puis confirmez.
3. Copiez le nouveau secret : c'est son seul affichage.
4. Installez-le dans votre service.

⚠️ L'ancien secret cesse d'être valide immédiatement. Votre service refusera les appels tant qu'il n'aura pas reçu le nouveau. Prévoyez la bascule.

Comment ajouter des en-têtes personnalisés ? #

Le bloc En-têtes personnalisés ajoute des en-têtes à chaque appel — par exemple un identifiant client attendu par votre logiciel.

1. Cliquez Ajouter un en-tête.
2. Saisissez le nom (lettres, chiffres et tirets uniquement, par exemple X-Client-Id) et la valeur.
3. Enregistrez.

À retenir : les valeurs sont chiffrées et jamais réaffichées (laisser vide conserve la valeur actuelle) ; le nom d'un en-tête déjà enregistré ne se modifie pas — retirez-le et ajoutez-en un nouveau ; et vous êtes limité à 20 en-têtes par intégration.

Comment composer le corps envoyé ? #

Le corps se compose au clavier, et les champs Sphère s'insèrent, ils ne se tapent pas.

1. Placez-vous dans le champ Corps JSON (ou dans la liste clé / valeur, selon le type de corps choisi).
2. Tapez / à l'endroit voulu : un sélecteur s'ouvre avec les champs du déclencheur, regroupés (champs du contact, de l'organisation, de l'utilisateur, du ticket, de l'événement, et vos champs personnalisés).
3. Filtrez à la frappe, puis validez pour insérer le champ.

Deux garanties importantes :

• Seuls les champs que vous insérez sont transmis. Sphère n'envoie jamais la fiche complète « au cas où ».
• Un champ qui n'existe pas pour le déclencheur choisi est signalé, et l'enregistrement est refusé tant qu'il reste dans le corps.

Comment voir ce qui va réellement partir ? #

Deux endroits, complémentaires :

• L'onglet Rendu du corps montre le corps une fois les champs remplacés.
• Le rail Requête générée montre toute la requête — le verbe, l'adresse, les en-têtes et le corps. Un sélecteur bascule entre Modèle (avec vos champs tels que vous les avez écrits) et Rendu sur un exemple.

L'exemple provient du catalogue du serveur : aucune donnée réelle n'est lue pour prévisualiser. Les secrets y sont masqués, et un en-tête déjà enregistré part avec sa valeur en base — elle n'est jamais relue, elle apparaît donc vide à l'écran.

💡 Le corps est ré-encodé à l'envoi : l'espacement de votre modèle n'est pas conservé, et un champ qui occupe toute une valeur garde son type d'origine (un nombre reste un nombre).

Mon corps JSON est refusé : comment trouver l'erreur ? #

Quand le corps JSON est mal formé, l'éditeur nomme la faute et la localise : « Corps JSON invalide », suivi de Ligne N, colonne N et d'un bouton Aller à l'erreur qui vous y emmène.

Les fautes les plus courantes sont expliquées en clair :

• virgule en trop avant la fermeture ;
• nom de propriété sans guillemets doubles ;
• chaîne de caractères non refermée ;
• deux-points manquants après le nom de la propriété ;
• il manque une virgule ou une accolade fermante ;
• un champ Sphère doit être placé entre guillemets doubles ;
• le document s'arrête avant d'être complet.

Une intégration dont le corps JSON est mal formé ne peut pas être enregistrée tant que la syntaxe n'est pas corrigée : vous ne risquez donc pas de découvrir le problème plus tard, en production.

Où trouver l'identifiant d'une intégration ? #

En haut de l'éditeur, sous le nom, la ligne Identifiant porte le code de l'intégration et un bouton Copier l'identifiant. C'est la référence à communiquer au support quand vous signalez un problème. Sur une intégration jamais enregistrée, la mention « attribué à l'enregistrement » s'affiche à la place.