Intégration API

Freshsales API : cadrer les flux CRM sans dérive durable

Jérémy Chomel Dawap
  • Publié le : 8 septembre 2024
  • Mis à jour le : 12 novembre 2026
  • Temps de lecture : 9 minutes
  1. Pour qui cadrer les entrées Freshsales
  2. Répartir les décisions entre marketing et ventes
  3. Distinguer un contact, une soumission et une opportunité
  4. Lire et mettre à jour un contact Freshsales
  5. Traiter un doublon et retrouver les relations
  6. Choisir ce qui doit arriver à temps
  7. Matrice de décision pour quatre entrées CRM
  8. Tracer une entrée du formulaire au CRM
  9. Plan d’action pour ouvrir le premier flux
  10. Erreurs fréquentes lors du rapprochement
  11. Guides complémentaires Freshsales
  12. Conclusion. Vérifier ce que chaque entrée peut changer
Portrait de Jérémy Chomel

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

Décisions pour le dossier fictif FS-2841
É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

  1. Relevez les correspondances sur un lot de contacts et d’opportunités sans autoriser de création.
  2. Ouvrez une mise à jour de fonction pour les fiches rapprochées et rejouez la même soumission.
  3. Simulez une réponse perdue, un contact ambigu et un changement de propriétaire dans l’interface.
  4. 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.

Portrait de Jérémy Chomel

Cadrer les entrées de votre CRM Freshsales

Définissez les identifiants du contact et de la soumission et les champs que le formulaire peut écrire.

Articles recommandés

Illustration du client Freshsales sous Symfony Intégration API SDK CRM Freshsales sous Symfony : erreurs API, retries et suivi de run Lire l'article
  • 29 janvier 2025
  • Lecture ~11 min

Un worker Symfony perd la réponse à un PUT Freshsales, puis la relecture se heurte à une limite de requêtes. Le client PHP distingue le refus, le résultat incertain et la valeur confirmée. Le cas fictif FS-2841 montre comment vérifier un contact et reporter la lecture sans rejouer la mise à jour ni modifier le responsable du deal.

Freshsales : arrêter une relance devenue incompatible avec l’opportunité Intégration API Freshsales : arrêter une relance devenue incompatible avec l’opportunité Lire l'article
  • 21 avril 2026
  • Lecture ~3 min

L’opportunité D-731 est clôturée, puis un événement ancien la présente encore comme ouverte. Sur ce dossier fictif, trois décisions montrent quand appliquer la séquence, quand bloquer la relance et quand attendre une lecture de contrôle avant d’envoyer un message.

Intégration API CRM : fiabiliser pipeline, ventes et marketing Intégration API Pipeline CRM : fiabiliser leads, comptes et opportunités Lire l'article
  • 17 août 2024
  • Lecture ~16 min

Une opportunité gagnée ne suffit pas à créer une commande ERP fiable. Identifiants, responsables, statuts et effets déjà produits doivent rester vérifiables quand un formulaire, le marketing et les ventes modifient le dossier. Ce guide propose des règles de décision, une recette de reprise et des parcours adaptés aux principaux CRM.

Réconciliation API : corriger les écarts entre systèmes Intégration API Réconciliation API : détecter et corriger les écarts Lire l'article
  • 27 mai 2025
  • Lecture ~32 min

La réconciliation API devient utile quand chaque écart est relié à une source de vérité, à une preuve d’exécution et à une action bornée. Elle évite les resync massifs et transforme un doute sur la donnée en décision lisible. Le dispositif conserve la fenêtre, le watermark, la clé métier et le droit de correction avant tout replay ou compensation.

Tester un formulaire et sa reprise dans Freshsales

Vérifiez le contact, l’opportunité et les relances sur un premier lot de recette.