Votre application Symfony reçoit une opportunité gagnée et demande la création d’un dossier dans l’ERP. La requête expire, puis le CRM envoie de nouveau le même événement. Le risque est de créer deux commandes pour le même client. Avant de relancer, l’équipe doit savoir si le dossier existe et quelle référence permet de le retrouver.
Dans un SDK CRM commun, Symfony peut partager le suivi de cette tentative, la gestion des accès et les règles de reprise. Chaque adaptateur conserve le format de ses identifiants, les associations qu’il sait lire et les erreurs propres à son API. Le service applicatif décide ensuite si la preuve disponible autorise une création dans l’ERP.
Le cas fictif ci-dessous montre comment attribuer la responsabilité de chaque écriture et traiter une réponse perdue. Il s’adresse aux équipes qui maintiennent plusieurs connecteurs ou préparent un deuxième CRM. Notre offre d’intégration API CRM couvre le cadrage des objets, le raccordement et la reprise.
Choisir un premier flux qui permet de vérifier le résultat
Prenons l’opportunité D-318 dans le compte CRM de l’équipe France. Le commercial la passe à l’étape gagnée. Le flux doit rattacher le dossier au client ERP C-481, ouvrir une seule demande de commande et inscrire la référence ERP au retour dans le CRM. Ces trois résultats se vérifient indépendamment.
Avant de brancher la file, écrivez les données minimales exigées à chaque étape. Une opportunité gagnée avec un compte inconnu reste consultable dans le CRM. La demande de commande attend une correspondance ERP confirmée. Si l’ERP répond avec une référence mais que le CRM refuse son inscription, la reprise porte sur l’écriture de cette référence.
- Entrée. Conserver l’instance CRM, le type d’objet, l’identifiant d’événement lorsqu’il existe et la version observée.
- Décision. Comparer l’étape lue dans le CRM, le lien de compte validé et les demandes de commande déjà enregistrées.
- Sortie. Relire le dossier côté ERP puis contrôler l’écriture de sa référence côté CRM.
- Reprise. Désigner la personne qui traite une correspondance ambiguë et identifier l’opération que le système peut reprendre seul.
Commencez avec une poignée de dossiers choisis pour leurs différences. Incluez un compte déjà lié, un compte inconnu et une opportunité dont la commande existe avant le pilote. Vous saurez ainsi si l’équipe retrouve les états antérieurs à la migration. Les règles de cadrage d’une API CRM aident à délimiter les objets et les accès avant ce test.
Dans quels cas mutualiser les connecteurs
Le socle commun se justifie lorsque deux flux reproduisent la même décision d’exploitation. Par exemple, le service de commandes doit retrouver une tentative par référence ERP, que l’événement soit arrivé par un webhook Pipedrive ou par une collecte Salesforce. Ce rapprochement appartient au service commun. Les mécanismes de collecte et leurs curseurs restent propres à leurs adaptateurs.
Avec un seul flux en lecture, un client configuré et un test du format retourné peuvent suffire. Réservez une interface partagée aux opérations que deux implémentations pourront réellement garantir. Une méthode read peut rapporter une opportunité lue ou signaler un échec. Pour partager une écriture, définissez aussi le résultat attendu, la condition qui autorise une nouvelle tentative et les cas qui exigent une intervention.
Comparez le travail demandé au support sur deux incidents récents. Si les deux équipes cherchent la même référence dans des écrans différents, normalisez cette information dans le journal. Si la deuxième équipe doit interpréter une association ou une étape absente chez le premier fournisseur, gardez ce choix dans son adaptateur ou dans le service métier qui le comprend.
Définir le propriétaire, la clé et le droit d’écriture
L’ERP détient la référence client et confirme la création du dossier. Le CRM détient l’étape de l’opportunité et le propriétaire commercial. La correspondance entre l’opportunité et le dossier est enregistrée dans le journal d’intégration après relecture. Ces règles décrivent le pilote. Sur un autre projet, un référentiel clients peut tenir la place de l’ERP pour l’identité.
Stockez les identifiants du fournisseur sous forme de chaînes opaques dans le contrat partagé. Un identifiant doit être interprété dans son instance et son type d’objet. Pour D-318, le lien associe l’instance France, l’objet opportunité, son identifiant CRM et le client ERP retenu. Le même identifiant dans une autre instance désigne un autre objet, même si son titre est identique.
Indiquez quels champs un événement peut modifier. Pour une association au compte, une propriété absente peut signifier que la réponse était partielle. Une valeur nulle explicite ne peut être interprétée comme une demande de dissociation que si le contrat de ce fournisseur et le flux l’autorisent. Une nouvelle adresse de facturation exige la validation prévue côté ERP avant d’être copiée dans la demande de commande.
Versionner la transformation sans rouvrir la commande
Un événement en attente a été transformé avec la version 3 du mapping. La version 4 normalise désormais les codes pays. Enregistrez la version utilisée pour chaque tentative. Une reprise peut relire la décision d’origine ou passer par une migration explicite avec ses contrôles. La version du mapping ne doit pas créer à elle seule une nouvelle clé pour la même commande. Une modification du montant passe par la procédure de correction de la commande, avec sa propre référence.
À la bascule, prenez un dossier créé avant la mise à jour puis rejouez son événement. La transformation peut produire une adresse normalisée différemment alors que l’effet métier reste le même. Le journal doit retrouver la réservation existante et montrer pourquoi l’ERP a reçu l’ancienne adresse. Cette trace permet au support d’instruire une correction au lieu de réouvrir la création.
Répartir les responsabilités dans Symfony
Le client HTTP construit les requêtes REST vers une origine configurée côté serveur. Donnez à chaque fournisseur un client qui lui est dédié, avec ses autorisations, ses délais et sa stratégie de journalisation. Gardez les jetons OAuth hors des messages de file. L’adaptateur valide le schéma de la réponse, convertit les champs dont le flux a besoin et transmet les erreurs avec leur contexte.
Le service applicatif arbitre la demande de commande. Il cherche le lien ERP, vérifie si l’état courant autorise l’écriture et réserve l’opération dans un journal persistant. Le handler Symfony peut planifier une nouvelle lecture ou transférer le dossier au support. Plusieurs handlers peuvent recevoir des messages relatifs à la même opportunité, donc la réservation doit résister à deux traitements concurrents, par exemple avec une contrainte unique en base.
Conservez les différences qui modifient une décision. Si un CRM expose un propriétaire en lecture sans autoriser sa modification avec les droits disponibles, le flux ne doit pas programmer cette écriture. Une interface de lecture et une capacité d’écriture séparée rendent cette limite visible. Documentez pour chaque capacité la permission requise, les champs retournés et la manière de vérifier un effet.
Une file peut conserver l’identifiant du dossier et le motif de reprise. Le handler recharge les données nécessaires avant l’appel. Pour une commande que le métier veut figer au moment de la validation, conservez l’instantané validé dans le journal applicatif, avec une référence vers les preuves d’origine. C’est la règle du flux qui décide quand relire et quand utiliser cet instantané.
Séparer collecte et ordre de traitement
Les webhooks et le polling peuvent alimenter le même traitement si le contrat d’entrée garde leur provenance. Pour un webhook, persistez l’enveloppe utile avant l’accusé de réception. Pour une collecte paginée, avancez le curseur après avoir enregistré les observations correspondantes. Si le stockage échoue, gardez le curseur de la dernière page durable pour retrouver les événements à traiter.
Une livraison répétée ou une page relue peut contenir des changements anciens. Dédupliquez les observations qui portent la même référence et relisez l’objet avant toute décision sensible. Quand le fournisseur expose une version exploitable, comparez-la à la dernière décision inscrite pour l’instance et l’objet. Le curseur décrit la progression de collecte. La version observée et les règles métier gouvernent l’écriture.
Ordonner les écritures selon les dépendances du flux
Pour D-318, le client de facturation doit être résolu avant l’envoi à l’ERP. Le contact peut être nécessaire pour transmettre un devis et facultatif pour ouvrir un dossier commercial. Inscrivez ces conditions dans le parcours concerné. Le même SDK peut ainsi traiter un prospect sans compte pour le marketing et exiger un compte vérifié au moment de commander.
Si l’événement « opportunité gagnée » arrive avant la mise à jour du compte, créez une attente sur le lien manquant. Au moment de reprendre, relisez l’état de l’opportunité. Si le commercial l’a rouverte entre-temps, conservez l’attente dans l’historique et arrêtez la création. Si le compte a fusionné, remplacez son ancien identifiant seulement après avoir établi la correspondance avec le survivant.
Une fois la commande confirmée, stockez sa référence avant d’écrire dans le CRM. Si ce retour échoue, le support doit voir « commande confirmée, référence CRM à inscrire ». Le parcours du pipeline CRM à la facture ERP détaille les étapes et leurs sources de vérité.
Décisions après un délai dépassé
Dédupliquez d’abord l’événement avec sa référence source lorsqu’elle est disponible. Réservez ensuite l’effet métier avec une clé stable, ici la combinaison de l’instance CRM, de l’opportunité et de la demande de commande concernée. Cette clé d’idempotence couvre deux événements différents qui demandent la même création. Si une opportunité peut porter plusieurs commandes, identifiez chacune par la référence de demande validée par le métier.
Enregistrez la tentative avant l’appel. Quand la réponse manque, passez-la à « résultat inconnu » et recherchez la clé externe côté ERP si l’API le permet. Si la recherche retourne un dossier du mauvais client, alors isolez le conflit et confiez-le au référent. Une référence qui correspond permet de confirmer l’écriture après contrôle du client et de l’état du dossier.
| Signal | Preuve à lire | Action |
|---|---|---|
| Le client ERP manque. | La correspondance a été validée par le référent. | Relire l’étape de vente puis reprendre le dossier concerné. |
| La création ERP expire. | La référence externe retrouve un dossier du bon client. | Confirmer le dossier et reprendre l’écriture de la référence CRM. |
| Le statut ERP reste incertain. | La recherche échoue ou sa visibilité est incomplète. | Laisser la tentative en attente de rapprochement. |
| Le retour vers le CRM est refusé. | Le dossier ERP confirmé figure dans le journal. | Corriger les droits ou le mapping puis reprendre ce seul retour. |
Un rejet de validation explicite appelle une correction du champ en cause. Pour une lecture transitoirement indisponible, définissez un budget de retry dans le contrat du flux, avec une durée maximale, un nombre de tentatives borné et un backoff compatible avec les limites du fournisseur. Une écriture au résultat inconnu suit la voie de rapprochement. Quand l’API offre une clé d’idempotence, vérifiez sa portée et sa durée de conservation avant de fonder la reprise dessus.
En réalité, une reprise plus lente peut réduire le délai de traitement des commandes. Si une seconde création déclenche une préparation en double, le support doit trouver les deux dossiers puis demander l’annulation du mauvais. Une lecture ciblée de l’ERP borne cette charge. Si le fournisseur ne propose aucune recherche fiable sur la référence, ouvrez une attente de rapprochement. Dans ce cas, fixez le délai d’escalade avec l’équipe qui peut inspecter la commande.
Donner au support de quoi décider
Pour chaque tentative, journalisez le fournisseur, l’instance, le type d’objet, la référence de l’effet métier, la version du mapping et la dernière preuve obtenue. Un identifiant de corrélation permet de suivre la même opération depuis le message jusqu’à la recherche ERP. Limitez l’accès aux données personnelles et conservez les éléments nécessaires à l’arbitrage selon la politique de rétention du projet.
Affichez ensemble le motif d’attente, l’heure de la dernière tentative et l’action suivante. Un dossier peut attendre un lien client validé, une réponse de l’ERP ou le rétablissement des droits CRM. Le support peut reprendre la lecture ou ouvrir une demande de correction. La validation de l’identité du client reste à la personne habilitée.
Fixez les alertes avec les utilisateurs du flux. Si la commande doit parvenir à l’entrepôt avant 16 h, un dossier au résultat inconnu mérite une alerte avant le départ du lot logistique. Mesurez l’âge de la plus ancienne tentative en attente et la part des dossiers qui demandent une action humaine. Ces deux mesures aident à repérer une accumulation même quand le débit HTTP paraît stable.
Quatre erreurs fréquentes à reproduire
- Deux workers reçoivent la même demande. Une seule réservation de commande aboutit. Vérifiez le nombre de demandes envoyées et la capacité du deuxième worker à retrouver l’état enregistré.
- La réponse disparaît après la création. Simulez un dossier déjà présent dans l’ERP au moment de la reprise. Le résultat attendu est la réutilisation de sa référence et l’écriture du retour CRM.
- Le client ERP lié contredit le client du dossier. Conservez les deux références et suspendez la reprise. Le référent peut établir si le lien d’origine est périmé ou si le dossier est attaché au mauvais client.
- Une correction commerciale précède le rejeu. Relisez l’étape, le propriétaire et la version du dossier. Une réouverture ou une correction protégée doit empêcher la réapplication de l’événement ancien.
Testez ensuite les contrats fournisseurs séparément. Une réponse simulée permet de provoquer un échec précis. La recette sur une instance de test doit confirmer les droits de lecture, le schéma réel, les limites de visibilité et la capacité de recherche par référence. Gardez un dossier avec des identifiants d’instances distinctes pour vérifier qu’aucun compte ne peut voir les données de l’autre.
Comparer les adaptateurs avec les guides par CRM
Pour éprouver la lecture d’un objet, comparez le modèle des associations dans le SDK HubSpot sous Symfony avec les autorisations et les états d’erreur du SDK Salesforce sous Symfony. Conservez une validation propre à chaque réponse.
Pour vérifier l’identité retournée, le SDK Pipedrive sous Symfony montre le rattachement d’un deal à la demande de lecture. Dans une installation Zendesk Sell existante, l’inventaire concerne les leads, les opportunités et les tâches commerciales. Zendesk annonce le retrait de Sell le 31 août 2027.
Exécuter un adaptateur de lecture
Le fichier PipedriveOpportunityReader.php montre une opération étroite. Il valide un identifiant numérique positif, appelle GET /api/v2/deals/{id}, puis vérifie que la réponse confirme le succès, porte le même identifiant et contient un propriétaire entier. Le résultat contient le fournisseur, l’identifiant, le propriétaire et les données rendues. Le contrat commun représente l’identifiant par une chaîne.
interface OpportunityReader
{
public function read(string $id): Opportunity;
}
Pour exécuter l’exemple, téléchargez l’archive des démonstrations Pipedrive, qui contient le contrat, le lecteur, l’objet retourné et check_reader.php. Le contrôle utilise le composant symfony/http-client et l’autoload Composer indiqué dans la commande. Il simule la lecture d’un deal, vérifie la méthode et l’URL, puis contrôle le rejet des identifiants invalides et d’une réponse portant un autre deal.
DAWAP_COMPOSER_AUTOLOAD=/chemin/vers/vendor/autoload.php php check_reader.php
Pour une recette connectée, injectez un client Symfony dédié, configuré avec l’origine de l’API de votre compte et le mécanisme d’authentification retenu. Vérifiez les délais et la politique de redirection dans sa configuration. Le contrat officiel de lecture d’un deal décrit les champs propres à Pipedrive. La documentation de MockHttpClient montre comment tester l’adaptateur sans requête externe.
Conclusion — décider quand ouvrir un deuxième flux
Rejouez le dossier D-318 dans votre environnement de recette. Une même demande doit conduire à une seule commande, puis au retour de sa référence dans le CRM. Lorsque la réponse est ambiguë, l’équipe doit pouvoir retrouver la tentative et le propriétaire de la prochaine action. Ajoutez le deuxième fournisseur après avoir rejoué ces décisions avec son propre contrat et ses propres données.
Pour l’ouverture, donnez au support un dossier témoin, l’accès au journal et la procédure de rapprochement. Vérifiez que les utilisateurs peuvent expliquer la décision à partir des références enregistrées. Les parcours d’intégration API couvrent aussi les flux qui dépassent le périmètre CRM.
Si plusieurs applications doivent partager ce parcours, notre accompagnement en intégration API CRM permet de cadrer les droits d’écriture, les règles de rapprochement et les scénarios de recette avant de connecter un nouveau périmètre.