Intégration API

Close CRM API : protéger le pipeline lors d’une reprise

Jérémy Chomel Dawap
  • Publié le : 29 septembre 2024
  • Mis à jour le : 12 novembre 2026
  • Temps de lecture : 9 minutes
  1. Identifier le lead, le contact et l’affaire
  2. Décider qui peut changer le pipeline
  3. Suivre les bons événements Close
  4. Retrouver une activité après une réponse perdue
  5. Reconstituer la journée du dossier CL-318
  6. Rattraper une interruption des webhooks
  7. Lire les écarts avec l’équipe commerciale
  8. Organiser la recette et le gel des écritures
  9. Rapprocher le pipeline du reporting
  10. Guides complémentaires pour le connecteur Symfony
  11. Conclusion
Portrait de Jérémy Chomel

À 11 h 02, une commerciale passe une affaire en gagné dans Close. Une minute plus tard, le connecteur reçoit une ancienne qualification issue du marketing et remet l’affaire en cours. Quand la téléphonie renvoie l’appel de conclusion, le rapport du jour en compte deux. Le support doit expliquer pourquoi une vente a disparu du tableau alors que les trois opérations ont réussi côté API.

Dans le dossier fictif CL-318, la demande web, l’appel et l’opportunité ont chacun leur propre référence. On peut donc restaurer l’historique de l’appel tout en conservant la décision commerciale. Le connecteur doit établir cette distinction avant de rejouer une écriture.

Le risque vient du droit d’écriture accordé au flux de qualification. Pour protéger le pipeline, attribuez aux ventes le dernier mot sur l’étape et faites traiter les appels indépendamment. Les ventes, le marketing et la téléphonie peuvent alors rejouer le même dossier de recette et vérifier ensemble ce que voit la commerciale dans Close.

Pour adapter ce contrat à vos pipelines et à vos outils, consultez notre accompagnement à l’intégration de Close CRM.

Identifier le lead, le contact et l’affaire

Dans Close, le Lead peut représenter un compte et regrouper plusieurs contacts. Une opportunité porte une affaire liée à ce lead. Si deux personnes d’une même société demandent une démonstration, leurs demandes peuvent se rattacher au même compte tout en restant deux entrées de prospection. Si ce compte a déjà une affaire active, le commercial décide à laquelle la demande se rapporte. La documentation Close sur les leads décrit les relations de ces objets.

Conservez trois correspondances. La référence du formulaire permet de reconnaître une demande déjà reçue. La clé de compte relie le référentiel au lead_id Close. La référence d’affaire permet de retrouver son opportunity_id, même si le compte en a plusieurs. Si la recherche renvoie deux comptes plausibles, le connecteur conserve la demande en attente avec les deux candidats et laisse la qualification confirmer le bon rattachement.

Décider qui peut changer le pipeline

Sur CL-318, le formulaire fournit le motif de la demande. Le marketing fournit le score et sa date. La téléphonie fournit le résultat de l’appel avec son identifiant d’origine. L’équipe de vente tient l’étape et le responsable de l’opportunité dans Close. L’ERP peut ensuite confirmer la référence d’un contrat quand la correspondance avec l’affaire est établie.

Cette répartition s’applique dans les deux sens. Si le score baisse après la conclusion, le connecteur peut actualiser le champ marketing sans renvoyer une copie de tout le dossier. Close applique les requêtes PUT comme des mises à jour partielles. Le connecteur envoie uniquement les champs autorisés à la source, comme indiqué dans la référence des requêtes Close.

Une correction d’étape passe par les ventes, avec un motif rattaché à l’affaire. Si un champ de statut est renvoyé par le marketing, le journal enregistre le refus et la source. Le guide d’intégration d’un CRM au SI aide à étendre cette répartition aux champs partagés avec la facturation et le support.

Quand un responsable change en cours de reprise

À 11 h 04, le responsable des ventes peut réattribuer CL-318 à une collègue qui gère le suivi après signature. Une notification plus ancienne peut encore mentionner la première commerciale. Conservez son identité comme auteur de la vente et l’identité de sa collègue comme responsable courant. Si un export reprend un seul champ pour ces deux usages, la reprise peut déplacer le crédit de la vente tout en affichant le bon responsable dans Close.

Le tableau peut avoir besoin des deux informations. Figez l’attribution dans la ligne de vente dès que sa règle métier est satisfaite. Mettez à jour le responsable courant dans la fiche d’affaire. Une modification rétroactive de l’attribution doit passer par la même validation qu’une correction du tableau des commissions.

Suivre les bons événements Close

Une notification lead.updated indique une modification du lead. La mise à jour d’un contact existant, d’une opportunité ou d’une activité peut faire évoluer la date du lead sans produire cette notification. Pour suivre une vente conclue et un appel terminé, choisissez les événements des objets concernés dans la liste des événements Close.

Pour une projection de l’état commercial, le récepteur vérifie la signature du webhook sur le corps reçu, enregistre le message durablement, puis confirme sa réception. Un traitement asynchrone relit l’opportunité à partir de son identifiant lorsque la décision dépend de l’état courant. Close documente que l’ordre de livraison des webhooks peut varier et que des changements proches peuvent être regroupés. Les dates de l’événement et de réception restent utiles au diagnostic. L’état de l’opportunité au moment de la décision se lit sur l’objet. Consulter les règles de livraison et de signature de Close.

Retrouver une activité après une réponse perdue

Supposons que le système de téléphonie transmette l’appel TEL-8841 et que la réponse à la création se perde. Le traitement enregistre l’opération comme indéterminée. Une contrainte d’unicité côté intégration sur la source et la référence de l’appel empêche deux consommateurs de relancer simultanément la même création.

La reprise cherche la correspondance déjà connue avec l’identifiant Close et consulte la preuve disponible sur le dossier attendu. Si l’architecture prévoit un champ de référence pour le type d’activité concerné, vérifiez que la valeur, le lead et le canal concordent. Une recherche par heure et numéro donne des candidats à examiner. Un appel de prospection et un rappel à une minute d’intervalle peuvent partager le même numéro.

Si la correspondance est certaine, associez l’identifiant Close à TEL-8841 et fermez l’opération. Si la cible n’est pas retrouvée de façon fiable, suspendez la création automatique et donnez au support la référence source, le lead attendu et l’heure d’envoi. Les possibilités de référence et de recherche dépendent du type d’activité retenu. Le guide sur les écritures idempotentes détaille la différence entre une réponse manquante et un échec confirmé.

Choisir une preuve avant d’autoriser le renvoi

Le support note si l’identifiant a été trouvé dans Close, confirmé par la téléphonie ou déduit d’une recherche. Quand deux appels correspondent, un opérateur choisit à partir de la référence d’origine ou laisse l’opération ouverte. Un délai écoulé indique que la vérification doit être escaladée. Le renvoi automatique exige une preuve exploitable que la première création a échoué avant l’écriture.

Paradoxalement, retarder le renvoi peut accélérer la résolution. Le support n’a qu’une création à rechercher et le commercial peut continuer de traiter l’affaire. Si la correspondance reste ambiguë après la revue, alors l’opérateur consigne les candidats et demande une confirmation à l’équipe qui tient la téléphonie.

Reconstituer la journée du dossier CL-318

  1. 10 h 46. La demande WEB-318 arrive pour un contact déjà connu. Le connecteur retrouve le compte et attache la demande à l’affaire sélectionnée. La campagne marketing garde son attribution sur la demande.
  2. 10 h 58. L’appel TEL-8841 se termine. La création de l’activité perd sa réponse. Le journal conserve 10 h 58 comme heure de l’appel et note à part l’heure de la tentative d’écriture.
  3. 11 h 02. La commerciale clôt l’affaire. Le reporting enregistre la vente avec l’identifiant de l’opportunité.
  4. 11 h 03. La qualification marketing de 10 h 50 arrive. Elle complète les champs marketing autorisés. La proposition de modifier l’étape est rejetée et tracée.
  5. 11 h 09. Le support retrouve l’activité créée et la rattache à TEL-8841. Le CRM présente un appel à 10 h 58 et une affaire gagnée à 11 h 02.

La recette compare le dossier Close, le journal du connecteur et la ligne de reporting. Une activité retrouvée doit expliquer le trou dans l’historique sans modifier l’heure de vente. Le support doit pouvoir retrouver les références sans ouvrir le contenu de l’appel ou du courriel.

Voici un extrait du journal interne attendu pour le rejet de 11 h 03. Il indique au support le champ refusé, la source de la demande et l’étape lue après le contrôle. La référence d’affaire permet d’ouvrir le dossier de recette.

{
  "case_id": "CL-318",
  "source": "marketing",
  "event_id": "QUAL-318-01",
  "received_at": "11:03",
  "field": "status",
  "requested": "qualified",
  "current": "won",
  "decision": "rejected",
  "reason": "sales_only"
}

Rattraper une interruption des webhooks

Lors d’une interruption, relevez la dernière fenêtre traitée et contrôlez l’état de la souscription avant de relancer. L’Event Log de Close donne accès à trente jours d’historique. Un événement peut être mis à jour après sa création lorsque plusieurs actions sont regroupées. Le rattrapage doit relire une courte fenêtre qui chevauche le dernier point de contrôle, puis ignorer les réceptions déjà traitées en tenant compte de ces mises à jour.

Avancez le point de contrôle après avoir enregistré les résultats de toute la fenêtre. Pour chaque opportunité concernée, comparez l’état Close et celui du reporting avant de republier. Au-delà de l’historique disponible, reconstruisez la projection des états courants et faites arbitrer les écarts avec les ventes. Signalez les mouvements dont la chronologie reste impossible à reconstituer.

Relire la frontière de la dernière fenêtre

Par exemple, si le dernier contrôle confirmé s’arrête à 11 h 00, le pilote peut relire les changements de 10 h 55 à 11 h 20. Le connecteur mémorise l’identifiant de l’événement et la dernière valeur de date_updated traitée. Une version déjà consommée peut être ignorée. Une mise à jour du même événement doit repasser dans le rapprochement. Sur une liste paginée triée des événements les plus récents aux plus anciens, parcourez toute la fenêtre avant de la déclarer complète. Voir les filtres et le tri de l’Event Log.

Gardez le point de contrôle de 11 h 00 si une page échoue. Lors du nouvel essai, la déduplication absorbe les événements déjà lus. Le traitement peut rouvrir une comparaison quand la version d’un événement a changé. L’équipe doit vérifier ce cas avec une mise à jour reçue à la frontière de la fenêtre.

Lire les écarts avec l’équipe commerciale

Le premier signal est une vente qui disparaît du rapport sans motif de réouverture. Comparez l’état de l’affaire, la dernière écriture acceptée et son origine. Une vente peut être rouverte volontairement. L’incident commence lorsque la source qui a changé l’étape ne disposait pas de ce droit ou que la projection a reculé sur une notification tardive.

Le second signal est un volume d’appels qui monte avec le nombre de réponses HTTP perdues. Comparez les identifiants de téléphonie avec les activités Close créées dans la même période. Les appels sans correspondance partent en revue. Les écarts connus peuvent ainsi être suivis à part du retard de traitement et des rejets de contrat.

Organiser la recette et le gel des écritures

Rejouez CL-318 dans une organisation de test qui reprend les statuts et champs utiles. Livrez les événements en ordre inverse, coupez la réponse après la création de l’appel, puis faites livrer le même message par deux consommateurs. La recette passe si elle retrouve un appel, la bonne affaire et un motif compréhensible pour chaque décision différée ou rejetée.

Le support doit pouvoir suspendre les écritures du flux fautif sur les opportunités tout en conservant les messages reçus. Après la correction, rejouez une affaire témoin, comparez son état au rapport, puis rouvrez par petits lots. Le seuil d’alerte pour un retard de file se fixe à partir du délai acceptable pour les relances et les tableaux de vente du client.

Dans ce pilote, geler le flux après une seule réouverture inexpliquée évite de diffuser la mauvaise étape au tableau des ventes. Un appel isolé en attente peut rester en rapprochement pendant que les activités confirmées continuent d’arriver. Le support traite les deux files séparément et l’équipe commerciale valide la reprise du flux gelé sur une affaire témoin.

Rapprocher le pipeline du reporting

Si une affaire est gagnée dans Close et absente du rapport, vérifiez que la projection contient le bon identifiant d’opportunité et que le filtre de période utilise la date commerciale convenue. Une importation de rattrapage effectuée lundi peut corriger la vente de vendredi. Gardez une date métier et une date de traitement afin que la correction atteigne le bon rapport.

Pour une réouverture autorisée, conservez les deux décisions successives dans le journal et recalculez la projection de l’affaire. Si la correction modifie un rapport déjà envoyé, alors signalez la ligne révisée et la raison de la révision à son destinataire.

Guides complémentaires pour le connecteur Symfony

Une fois les objets, les droits d’écriture et la reprise définis, passez au guide du SDK Close CRM sous Symfony pour répartir ces responsabilités entre le client HTTP, le traitement des messages et les journaux d’exécution.

Si les rapports contiennent déjà des écarts, utilisez le guide de réconciliation entre source et cible pour isoler les identifiants à vérifier et borner la reprise aux affaires concernées.

Conclusion

Commencez par une affaire qui a déjà posé un problème au support. Identifiez son lead, son opportunité et les références des activités qui viennent d’un outil externe.

Faites valider qui peut écrire l’étape et ce qu’un événement tardif peut encore enrichir. Une correction légitime doit rester visible dans le même historique que la décision initiale.

Avant d’étendre le flux, demandez à une personne des ventes de vérifier le dossier obtenu après l’interruption. Elle doit retrouver son appel et son affaire sans retravailler les données du CRM.

Notre équipe peut cadrer ce pilote et les règles de rapprochement avec vos outils dans le cadre d’une intégration Close CRM sur mesure.

Portrait de Jérémy Chomel

Reliez Close à votre téléphonie et à votre marketing

Définissez qui peut modifier le pipeline et comment retrouver les appels déjà transmis.

Articles recommandés

Lecture d’une opportunité Close CRM avec Symfony Intégration API SDK Close CRM sous Symfony : lire et vérifier une opportunité Lire l'article
  • 15 novembre 2024
  • Lecture ~10 min

Implémentez un client Symfony qui retrouve une opportunité Close, vérifie son organisation et son lead, puis transmet le délai de quota au worker. Le dossier fictif SYM-204 aide à tester une réponse perdue, une mauvaise correspondance et deux lectures qui arrivent dans le désordre dans le tableau de suivi.

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.

Testez la reprise sur une affaire Close

Vérifiez avec les ventes que les appels, les opportunités et le reporting restent cohérents après une interruption.