Une personne déjà suivie dans Freshsales renvoie un formulaire après un salon. Le formulaire contient sa nouvelle fonction et le nom de l’entreprise. Si l’import applique aussi une règle d’attribution par défaut, une simple mise à jour du contact peut réaffecter un dossier qu’un commercial travaille depuis plusieurs semaines.
Le risque augmente lorsque le marketing envoie une soumission, le connecteur l’interprète comme un nouveau contact et une automatisation déclenche une relance. Le contrat d’intégration doit commencer par séparer ces trois décisions. Chacune a sa clé, sa source et ses conditions de reprise.
Pour une intégration API Freshsales, relevez les champs que les formulaires peuvent enrichir et les décisions qui restent aux ventes. Les tests doivent vérifier le contact, son compte, son opportunité et les actions déclenchées.
Le dossier fictif FS-2841 sert de fil conducteur. Une soumission de formulaire est reçue deux fois pendant qu’un commercial prépare l’opportunité D-731. La fonction peut changer. Le responsable et l’étape restent soumis aux règles des ventes.
Pour qui cadrer les entrées Freshsales
Ce cadre concerne les équipes qui alimentent Freshsales depuis un formulaire, un outil marketing et un import d’ERP. Une source unique peut être vérifiée à partir de quelques fiches. Dès que plusieurs entrées se partagent la création et que le CRM déclenche des relances, une erreur de rapprochement peut changer le destinataire, le responsable ou le contenu du suivi.
Deux indices permettent de circonscrire le problème. La même demande de démonstration apparaît dans les portefeuilles de deux commerciaux. Ou une relance reste programmée alors que le dossier a changé d’étape. Dans les deux cas, commencez par suivre un identifiant de soumission jusqu’au contact et à l’opportunité concernés.
Répartir les décisions entre marketing et ventes
Limiter les champs écrits par chaque entrée
Le formulaire peut proposer la fonction et conserver la campagne qui a produit la demande. Freshsales conserve l’attribution commerciale et l’étape de l’opportunité. Le système de gestion peut fournir une référence client confirmée. Ces champs ont des usages distincts, même lorsqu’ils apparaissent dans la même fiche.
Attribuez chaque champ à une source et définissez ce qui se passe quand sa valeur est absente, vide ou contestée. Une fonction absente de la deuxième soumission ne justifie pas de supprimer la valeur existante. Le guide de raccordement d’un CRM détaille la répartition des responsabilités entre les applications.
Distinguer un contact, une soumission et une opportunité
Enregistrer les correspondances avant l’upsert
Une nouvelle soumission peut provenir du même contact. La clé de soumission permet d’écarter la répétition d’un même message. La clé du contact permet de retrouver sa fiche. Une opportunité exige sa propre référence, car une personne peut ouvrir deux demandes pour des établissements ou des projets différents.
Conservez dans le connecteur la correspondance entre la référence source et l’identifiant Freshsales retourné. Si une adresse a changé depuis le premier formulaire ou correspond à une boîte partagée, vérifiez la relation au compte avant de réutiliser cette adresse comme identifiant. Sur FS-2841, le doublon de soumission et le rapprochement du contact produisent deux traces distinctes.
Freshworks documente un upsert par identifiant ou par champ déclaré unique dans le formulaire. Une recherche ambiguë peut retourner les identifiants des doublons. Cette réponse donne les fiches à examiner. L’équipe décide ensuite quelle fiche conserver et contrôle les relations avant d’autoriser une fusion. Upsert d’un contact dans l’API Freshsales
Lire et mettre à jour un contact Freshsales
Vérifier la fiche et limiter le corps du PUT
Dans le cas fictif, l’instance a déjà associé FS-2841 au contact numérique 2841. L’API Freshsales documentée utilise l’URL de compte ou de bundle indiquée dans les réglages et un en-tête d’authentification par clé. Le chemin ci-dessous suppose un bundle dont le préfixe est /crm/sales. Utilisez l’URL de l’instance et gardez la clé hors des traces. Authentification Freshsales
GET /crm/sales/api/contacts/2841?include=sales_accounts
Authorization: Token token=<API_KEY>
PUT /crm/sales/api/contacts/2841
Authorization: Token token=<API_KEY>
Content-Type: application/json
{"contact": {"job_title": "Responsable logistique"}}
La lecture sert à vérifier l’identifiant et le compte attendu. Le PUT envoie uniquement la fonction dans l’objet contact. Les champs de responsable, les relations de compte et l’étape de l’opportunité restent hors de cette demande. Contrôlez après écriture les valeurs et les effets des automatisations configurées. Mise à jour d’un contact Freshsales
Traiter un doublon et retrouver les relations
Si deux fiches correspondent à la même personne, le référent CRM relève leurs identifiants, leurs comptes et les opportunités ouvertes avant toute fusion. Il identifie la fiche conservée et vérifie le résultat dans la configuration de l’instance. Le connecteur reprend ensuite la correspondance vers l’identifiant conservé.
Une réponse perdue juste après une création demande de rechercher la fiche avant une nouvelle création. Après une mise à jour, relisez le champ attendu et l’identifiant. Vérifiez séparément la création d’une tâche, l’envoi d’un message ou tout autre effet aval. La présence de la valeur dans Freshsales ne prouve pas l’exécution de ces effets.
Choisir ce qui doit arriver à temps
Une demande de démonstration peut justifier une notification rapide au responsable. Un changement de fonction peut attendre le prochain lot si aucune action ne dépend de cette valeur. L’ordre se décide en fonction de la conséquence métier de l’événement et du moment où elle se produit.
La décision d’envoyer une relance doit tenir compte de l’état de l’opportunité au moment de l’envoi. Si le signal de changement d’étape arrive après le déclencheur, une décision calculée au moment de l’import est déjà ancienne. La mécanique d’envoi et les actions disponibles dépendent de l’outil qui exécute la séquence.
Matrice de décision pour quatre entrées CRM
| État observé | Action du connecteur |
|---|---|
| La même soumission arrive deux fois. | Conserver la première décision. Ne pas créer un second contact. |
| Une nouvelle soumission apporte la fonction. | Mettre à jour la fonction et laisser l’opportunité D-731 à son responsable. |
| Deux contacts correspondent à la même adresse. | Isoler l’entrée et faire vérifier les comptes et opportunités. |
| D-731 change d’étape avant la relance. | Réévaluer l’envoi avec l’état commercial courant. |
Tracer une entrée du formulaire au CRM
Rendre chaque décision retrouvable
La journalisation garde la référence de soumission, la source, l’identifiant Freshsales, le champ modifié et le résultat. Quand deux messages concernent le même contact, la file doit permettre de retrouver leur ordre d’origine et la règle de priorité du contrat. Le support peut alors expliquer une action sans demander les données du formulaire ni la clé API.
Prévoyez un repli sur les écritures de la seule source concernée. Conservez les entrées en attente et attribuez au référent CRM la responsabilité de valider les correspondances avant la reprise. Si une source a perdu ses droits, vérifiez ce qui reste visible avec le compte technique avant de décider qu’une fiche manque.
Plan d’action pour ouvrir le premier flux
- Relevez les correspondances sur un lot de contacts et d’opportunités sans autoriser de création.
- Ouvrez une mise à jour de fonction pour les fiches rapprochées et rejouez la même soumission.
- Simulez une réponse perdue, un contact ambigu et un changement de propriétaire dans l’interface.
- Vérifiez les opportunités avant et après le lot, puis testez la décision d’envoyer une relance sur un dossier dont l’étape a changé.
Un pilote fictif peut prendre douze soumissions dont quatre cas à examiner, avec des réponses et des relations préenregistrées. Les ventes vérifient l’attribution des opportunités. Le support doit retrouver l’entrée à l’origine de chaque action. Au premier doublon créé ou changement de responsable hors règle, suspendez l’élargissement du flux et reprenez le dossier en cause.
Erreurs fréquentes lors du rapprochement
Utiliser le nom ou l’adresse comme seule preuve peut rapprocher deux contacts de sociétés différentes. Confondre la référence de soumission avec celle du contact peut créer une nouvelle fiche pour chaque formulaire. Enfin, transmettre le contact et le deal dans une même reprise peut réappliquer une ancienne étape après la correction du commercial.
Testez une fiche à laquelle le compte technique n’a pas accès et une autre dont le contact existe mais dont l’opportunité a été rattachée à un autre compte. Un retour exploitable doit distinguer la restriction d’accès, le mauvais rattachement et le doublon. Le nombre d’appels réussis ne suffit pas à repérer ces écarts.
Guides complémentaires Freshsales
Le SDK Freshsales sous Symfony approfondit la gestion de l’accès, des requêtes et des reprises au niveau du client technique.
Le guide sur les relances Freshsales après un changement d’opportunité suit la décision d’envoi jusqu’au dernier contrôle d’éligibilité.
Conclusion. Vérifier ce que chaque entrée peut changer
Sur FS-2841, deux passages du formulaire donnent une seule décision sur la fiche. Le changement de fonction reste séparé de l’attribution du deal et du déclenchement de la relance.
Le pilote doit vérifier la clé de chaque objet, la liste des champs modifiables et le traitement après une réponse perdue. Ces contrôles permettent de reprendre un dossier sans réécrire toute son histoire.
Ouvrez les créations et les relances quand l’équipe sait retrouver une soumission, identifier son contact et expliquer pourquoi une action a été suspendue.
Notre équipe d’intégration API Freshsales peut cadrer les correspondances et préparer avec vos équipes les tests sur les formulaires, les opportunités et les séquences.