Intégration API

API SuiteCRM : synchroniser les comptes, contacts et activités

Jérémy Chomel Dawap
  • Publié le : 25 septembre 2024
  • Mis à jour le : 12 novembre 2026
  • Temps de lecture : 12 minutes
  1. Inventorier l’instance avant de choisir l’API
  2. Identifier les comptes, les contacts et leurs relations
  3. Lire et mettre à jour le compte depuis l’ERP
  4. Vérifier les effets des workflows et des hooks
  5. Limiter les droits du client OAuth
  6. Rapprocher les écarts entre SuiteCRM et l’ERP
  7. Rendre la décision visible au support
  8. Recetter les mises à niveau et la reprise
  9. Inventorier les extensions qui touchent le flux
  10. Plan d’action avant la bascule
  11. Pour qui commencer par un flux de comptes
  12. Erreurs fréquentes et décision à prendre
  13. Recetter le compte FR02-00741
  14. Approfondir Symfony et la reprise des activités
  15. Conclusion — savoir quand confirmer une synchronisation
Portrait de Jérémy Chomel

L’ERP renvoie une mise à jour pour le client 00741. Deux comptes portent ce numéro dans SuiteCRM, chacun pour une société différente. Une écriture sur le mauvais compte suffit à fausser les relances et à rendre l’historique difficile à reconstituer.

Le risque est de laisser le connecteur choisir une fiche sur un numéro ou un nom qui ne désigne pas à lui seul le compte. Le raccordement doit commencer par une correspondance vérifiable entre la société ERP, sa référence client et l’identifiant du compte SuiteCRM.

Le cas fictif suit le compte FR02-00741, dont l’ERP corrige la raison sociale à la révision 17. Il montre comment trouver la fiche, tester les droits, contrôler les activités liées et reprendre la synchronisation si la réponse est perdue.

Une intégration API SuiteCRM se cadre à partir de la version installée, des modules utilisés et des règles que chaque équipe doit pouvoir vérifier en recette.

Inventorier l’instance avant de choisir l’API

Relevez la version de SuiteCRM, l’URL publique de l’instance et les endpoints utilisés par les intégrations existantes. La documentation distingue l’API V8, fondée sur JSON:API et OAuth2, de l’API historique V4.1. Le numéro de l’API et celui de l’application sont deux informations à relever séparément. Versions de l’API SuiteCRM

Un connecteur historique peut être indispensable au quotidien. Isolez son contrat et testez le remplacement sur un flux avant d’y basculer les autres producteurs. Pour un nouveau raccordement, vérifiez que les opérations V8 nécessaires sont accessibles avec le client de recette.

Avec le client de recette, consultez /Api/V8/meta/modules et /Api/V8/meta/fields/Accounts pour relever les noms exposés. Comparez ces résultats aux écrans utilisés par les équipes. Un champ visible dans un formulaire peut porter un autre nom dans l’API.

Identifier les comptes, les contacts et leurs relations

Dans le pilote, la clé source du compte réunit la société FR02 et la référence client 00741. Le CRM garde son propre identifiant. Un client de la société BE01 peut porter le même numéro ERP. L’intégration vérifie donc la clé complète, puis conserve la correspondance avec le compte SuiteCRM résolu.

Le référentiel ERP fournit la raison sociale facturée. L’équipe commerciale décide du responsable et du stade de l’opportunité. Le connecteur n’envoie que les champs autorisés par sa source. Le cadrage des échanges CRM donne la grille pour décider qui écrit chaque champ.

Résolvez les comptes avant de relier les contacts et les opportunités. Pour les activités, relevez les relations qui doivent être conservées et leurs noms techniques. L’API V8 adresse ces relations par un nom de lien défini dans le module. Modules et relations de l’API V8

Lire et mettre à jour le compte depuis l’ERP

Résoudre la fiche avec sa clé complète

Le pilote stocke FR02-00741 dans un champ personnalisé de compte nommé erp_customer_ref_c. Confirmez que votre instance expose le champ, puis vérifiez la correspondance exacte des résultats. Un identifiant SuiteCRM déjà connu doit pointer vers la même clé source lors de la lecture de contrôle.

La recherche du pilote utilise GET /Api/V8/module/Accounts avec le paramètre filter[erp_customer_ref_c][eq]=FR02-00741. Demandez la clé et le nom, puis comparez la clé complète dans les résultats. Vérifiez le nombre de correspondances avant de retenir un identifiant, même si le client API vous présente les résultats par pages.

Si plusieurs comptes correspondent, alors le connecteur isole le dossier. Si aucun résultat ne remonte, vérifiez d’abord que le client OAuth est autorisé à lire le périmètre attendu. Une fiche invisible à cause des droits peut déjà exister. Une fois l’absence confirmée, une création éventuelle doit suivre le parcours prévu et éviter deux demandes simultanées pour la même clé.

Écrire uniquement le champ autorisé

Le cas fictif remplace « Atelier Brune SAS » par « Ateliers Brune SAS ». Dans cette organisation de recette, la raison sociale est portée par name. L’API V8 documente le PATCH /Api/V8/module, avec le module et l’identifiant dans data. L’exemple utilise un identifiant fictif. Mettre à jour un enregistrement SuiteCRM

{
  "data": {
    "type": "Accounts",
    "id": "6ea0cdad-1de7-42cb-8e2c-fffb55107741",
    "attributes": {
      "name": "Ateliers Brune SAS"
    }
  }
}

Le numéro de révision 17 est conservé dans le journal du connecteur. Il n’est pas transmis comme un champ natif de l’API. Si la révision 16 revient après la 17, alors le journal empêche son application. Gardez cette décision par clé source et protégez la mise à jour du journal contre deux traitements concurrents.

Une relance de la révision 17 retrouve la décision existante. Si le même numéro de révision arrive avec un contenu différent, alors suspendez le traitement et comparez les deux événements à la source. Une modification concurrente du champ dans SuiteCRM doit aussi avoir une règle de traitement explicite.

Vérifier les effets des workflows et des hooks

Inventoriez les règles et les hooks installés sur le module qui reçoit l’écriture. Un hook peut modifier une fiche, enregistrer un effet aval ou déclencher une nouvelle sauvegarde. Testez le chemin exact de l’API dans l’environnement de recette, avec les règles activées. Événements des hooks SuiteCRM

Si une modification de raison sociale déclenche une notification dans votre instance, relevez son identifiant ou sa trace de traitement. La relecture du compte confirme le champ. La trace de notification confirme l’effet aval. En cas de timeout, vérifiez les deux avant d’autoriser une nouvelle écriture.

Limiter les droits du client OAuth

Pour un service sans interaction humaine, SuiteCRM documente le flux OAuth2 client_credentials sur /Api/access_token. Identifiez l’utilisateur associé au client quand cette configuration s’applique à votre version. Vérifiez les droits avec le jeton du connecteur dans chaque environnement. Authentification de l’API V8

Les rôles et groupes de sécurité définissent les opérations autorisées et les fiches accessibles. Faites réussir une mise à jour sur le groupe du pilote et vérifiez que la même opération est refusée hors périmètre. Séparez les secrets de recette et de production. Le journal doit indiquer le module, la référence et la décision sans copier les secrets ni les fiches complètes. Rôles et groupes de sécurité SuiteCRM

Rapprocher les écarts entre SuiteCRM et l’ERP

Contrôlez les comptes rapprochés, ceux dont la clé est inconnue et ceux qui nécessitent une correction. Une réponse réussie peut laisser une relation manquante. Pour un compte, comparez les champs contractuels et les identifiants des objets liés, puis confiez les anomalies à la personne qui peut corriger la source.

L’API propose une pagination par numéro et taille. Lorsqu’une collection évolue pendant la lecture, un simple compteur de pages ne prouve pas que chaque compte a été parcouru. Après une interruption, repartez du dernier périmètre rapproché et dédupliquez les observations par identifiant. La réconciliation entre source et cible détaille les preuves à conserver.

Gardez un relevé de contrôle par société ERP. Si une lecture retourne le bon nombre de comptes mais omet FR02-00741 et reprend BE01-00741 deux fois, le total peut rester exact. Le rapprochement des couples société et référence révèle à la fois l’absence et le doublon.

Rendre la décision visible au support

Le support doit retrouver la fiche à partir de sa référence ERP ou de son identifiant SuiteCRM. Affichez la dernière révision confirmée, l’état de la file et la cause du blocage. Cela évite de corriger manuellement la raison sociale pendant que le connecteur attend une décision sur le même compte.

Pour la traçabilité de la file, conservez l’entrée source, la corrélation et le résultat de la lecture. Pour FR02-00741, le journal indique si la révision 17 a été proposée, confirmée ou placée en attente de vérification. En cas de doublon, le support transmet les identifiants en concurrence au responsable des données. Si le résultat est incertain, il consulte la fiche et les effets aval avant de rouvrir la file.

Recetter les mises à niveau et la reprise

Pour préparer une mise à niveau, reproduisez la version, les personnalisations et les droits du connecteur sur une instance de recette. Vérifiez la restauration de la base et des fichiers, puis rejouez les lectures, les modifications et les relations nécessaires au pilote. Mise à niveau de SuiteCRM 8

Prévoyez un repli distinct pour le CRM et pour les échanges. La restauration du CRM ne rétablit pas automatiquement l’état des autres systèmes. Conservez les messages reçus pendant la suspension, puis rapprochez les modifications déjà propagées avant de reprendre les écritures.

Avant la remise en service, contrôlez l’identifiant du compte, le dernier événement confirmé et les relations présentes dans l’instance restaurée. Si l’ERP a déjà consommé un effet, rattachez-le à l’événement d’origine avant toute correction. Cette comparaison doit figurer dans la recette de restauration.

Inventorier les extensions qui touchent le flux

Identifiez les champs personnalisés, modules ajoutés, hooks et tâches planifiées que le pilote utilise. Pour chaque dépendance, relevez qui la maintient et le scénario de recette qui révèle une rupture. Une extension peut aussi modifier les valeurs qu’une API permet de lire ou d’écrire.

Si un module personnalisé fournit une relation indispensable, alors testez cette relation avec l’utilisateur du connecteur avant la bascule. Si une tâche planifiée republie des changements vers l’ERP, vérifiez que le compte déjà traité ne déclenche pas un aller-retour supplémentaire.

Plan d’action avant la bascule

Commencez par un compte identifié et un champ dont l’ERP est maître. Validez la lecture avec les droits de recette, puis contrôlez le résultat du PATCH et l’effet éventuel des règles de l’instance.

  • Documenter la clé source, le module, le champ et le système autorisé à l’écrire.
  • Tester un accès refusé, deux correspondances et une coupure après l’envoi.
  • Nommer le responsable qui peut suspendre la file et décider d’une reprise.

Le runbook décrit comment geler les écritures, préserver la file et reprendre depuis les dernières révisions confirmées. La responsabilité de la remise en service revient à la personne qui peut rapprocher le CRM et l’ERP. Le seuil d’arrêt dépend du délai et des dossiers que le support peut traiter.

Pour qui commencer par un flux de comptes

Ce pilote convient à une équipe qui alimente SuiteCRM depuis un ERP ou qui a déjà plusieurs sociétés dans son référentiel. Il permet d’observer l’identité, les droits et la reprise avant d’ouvrir les contacts, opportunités ou activités.

Si une équipe utilise déjà des comptes consolidés et rencontre surtout des ruptures d’historique après fusion, commencez par la lecture des activités et de leurs relations. Le premier flux doit traiter le problème que le support peut reproduire.

Erreurs fréquentes et décision à prendre

Le risque est de croire qu’un timeout signifie que le compte est resté intact. Une écriture peut avoir été appliquée avant la coupure. Recherchez la fiche liée à la demande et comparez les champs autorisés et les effets attendus. Si la relecture est insuffisante, gardez le dossier en attente avec sa corrélation.

Un rejet de droits exige une revue du client et du périmètre. Une clé partagée par plusieurs fiches exige un arbitrage sur les comptes. Une révision ancienne s’écarte du flux avant l’appel. Ces décisions évitent d’accumuler des relances qui allongent le délai de traitement et augmentent la charge support.

Recetter le compte FR02-00741

En recette, créez deux comptes fictifs qui portent le numéro 00741 dans deux sociétés. Associez le compte FR02 à un contact et à une activité. Exercez ensuite les cas suivants avec les mêmes droits que le connecteur.

Décisions attendues pour le compte ERP 00741
ObservationDécisionPreuve attendue
FR02, révision 17Appliquer la raison sociale.Même compte et mêmes liens.
BE01, même numéroÉcarter ce résultat.Compte BE01 intact.
Deux comptes FR02Suspendre l’écriture.Deux identifiants à arbitrer.
Accès refusé hors groupeArrêter ce flux.Fiche hors périmètre intacte.
Révision 16 après la 17Écarter l’événement ancien.Révision 17 maintenue.
Réponse perdueRelire compte et effets.État et action aval confirmés.

À la clôture, comparez la raison sociale, le responsable et les liens avant et après l’écriture. La révision 17 doit être confirmée une fois sur FR02. Le contact et l’activité restent sur le même compte. Ce scénario fixe des résultats attendus à observer sur votre installation.

Approfondir Symfony et la reprise des activités

Le SDK SuiteCRM sous Symfony détaille l’authentification, la séparation du client et du traitement métier, ainsi que la reprise des appels.

Pour une migration ou une fusion de comptes, le dossier SuiteCRM et la conservation des activités approfondit les contrôles sur les appels, réunions, notes et relations.

Conclusion — savoir quand confirmer une synchronisation

Confirmez le compte à partir de la société, de la référence ERP et de l’identifiant SuiteCRM. Une fois ce lien établi, limitez l’écriture au champ que l’ERP peut modifier.

Le pilote FR02 doit montrer que la révision 17 est visible, que BE01 reste intact et que les relations du compte sont préservées.

Après une réponse perdue, le support doit pouvoir retrouver la fiche et déterminer si un effet a déjà été produit avant d’autoriser la reprise.

Pour cadrer votre intégration API SuiteCRM, Dawap vous accompagne sur le choix du premier flux, les droits du connecteur et la recette avec vos équipes CRM et ERP.

Portrait de Jérémy Chomel

Préparer votre premier flux SuiteCRM

Identifiez les comptes, les droits du connecteur et les cas de reprise à tester.

Articles recommandés

SuiteCRM sous Symfony Intégration API SDK SuiteCRM sous Symfony : vérifier une écriture avant de la rejouer Lire l'article
  • 1er février 2025
  • Lecture ~14 min

Un worker perd la réponse à un PATCH SuiteCRM. Le compte a peut-être déjà changé. Un exemple Symfony relit la fiche, contrôle l’identifiant et la référence ERP, puis compare la valeur attendue. Le support peut alors vérifier les effets produits et décider si une nouvelle écriture est encore nécessaire.

SuiteCRM : préserver les activités lors des imports et des fusions Intégration API SuiteCRM : préserver les activités lors des imports et des fusions Lire l'article
  • 16 avril 2026
  • Lecture ~3 min

Après une fusion SuiteCRM, une note a changé de compte et un appel a perdu son lien. Un relevé de quatre activités montre comment vérifier les rattachements, restaurer une relation et mettre un dossier en attente si son parent reste introuvable. Le contrôle se fait activité par activité avant de relancer l’import.

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.

Relier SuiteCRM à votre ERP

Vérifiez les correspondances et la reprise des écritures avant d’élargir la synchronisation.