Une commande reste en attente dans l’ERP. Le worker Symfony lit son compte dans Salesforce et reçoit HTTP 403. Le support doit savoir s’il s’agit d’un droit absent ou d’un quota épuisé. Une relance automatique qui traite tous les 403 de la même façon prolonge le blocage.
En pratique, un SDK Salesforce doit restituer le résultat du transport, tandis que le traitement métier décide de la reprise. Le client sait lire un compte ou soumettre un lot. Le worker sait quelles opérations peuvent être répétées et quelle preuve permet de libérer une commande.
Le parcours ci-dessous montre comment structurer ces responsabilités, avec un exemple Symfony de lecture et des cas de recette REST, Bulk et Pub/Sub. Pour les appliquer à vos objets et à vos règles de gestion, retrouvez l’offre d’intégration Salesforce avec votre système d’information.
Pour qui construire un SDK Salesforce sous Symfony
Un SDK interne devient utile lorsque plusieurs workers ou services Symfony partagent les mêmes accès et opérations Salesforce. Ils doivent appliquer la même version d’API, donner le même sens aux réponses et laisser au support des traces comparables. Une lecture unique peut commencer avec un client simple.
Pour un premier périmètre, choisissez une opération lisible de bout en bout. Une commande en attente doit retrouver son compte Salesforce, son tiers ERP et le statut de la dernière écriture. Le pilier sur l’architecture de l’API Salesforce aide à choisir le canal avant de construire le client.
Définir les objets et les champs que le client peut écrire
Avec le compte technique, inspectez les métadonnées des sObjects et vérifiez les champs accessibles. Confirmez ensuite en sandbox les règles de validation, les champs obligatoires et les Flows qui s’exécutent après l’écriture. Une réponse de métadonnées et un test métier couvrent des étapes différentes. Référence Salesforce sur sObject Describe.
Le mapping doit indiquer quelle source écrit chaque champ. Si Salesforce fait foi pour OwnerId, alors un import ERP peut enrichir le compte sans reprendre ce champ. Pour un Contact, distinguez la valeur absente d’une demande d’effacement et contrôlez qui peut appliquer celle-ci.
Séparer le client HTTP du traitement métier
Injectez un client HTTP par configuration Salesforce. Limitez-le à l’URL d’instance validée pour l’organisation. Le composant de transport prépare le chemin, transmet le jeton et interprète la réponse. Les adaptateurs métier traduisent ensuite les objets Salesforce en données du domaine et décident des champs à écrire.
Lire un compte et qualifier les erreurs
Cet exemple reçoit un HttpClientInterface déjà configuré avec une base_uri HTTPS de confiance. La version validée est de la forme vXX.X. Le jeton OAuth provient du fournisseur d’accès, qui reste extérieur à la fonction. Le code renvoie un état au worker et laisse remonter une erreur de transport ou un corps invalide sur un succès. Clients Symfony à portée limitée et lecture d’un enregistrement Salesforce.
use Symfony\Contracts\HttpClient\Exception\DecodingExceptionInterface;
use Symfony\Contracts\HttpClient\HttpClientInterface;
function readAccount(
HttpClientInterface $client,
string $version,
string $id,
string $token,
): array {
$path = sprintf(
'/services/data/%s/sobjects/Account/%s',
rawurlencode($version),
rawurlencode($id),
);
$response = $client->request('GET', $path, [
'auth_bearer' => $token,
'max_redirects' => 0,
'timeout' => 5,
'max_duration' => 10,
]);
$status = $response->getStatusCode();
if ($status === 200) {
$account = $response->toArray();
if (!is_string($account['Id'] ?? null) || $account['Id'] === '') {
throw new UnexpectedValueException('Compte sans identifiant.');
}
return ['state' => 'found', 'account' => $account];
}
try {
$errors = $response->toArray(false);
} catch (DecodingExceptionInterface) {
$errors = [];
}
$codes = array_column($errors, 'errorCode');
$state = match (true) {
$status === 403 && in_array('REQUEST_LIMIT_EXCEEDED', $codes, true)
=> 'quota',
$status === 401 => 'auth',
$status === 403 => 'refused',
$status === 404 => 'unverified',
$status === 429 || $status >= 500 => 'transient',
default => 'review',
};
return ['state' => $state, 'status' => $status];
}
La fonction classe la réponse d’une lecture. Le worker possède la responsabilité de la reprise et fixe le seuil de tentatives. Vérifiez les décorateurs HTTP installés, notamment retry_failed et RetryableHttpClient. Un client partagé avec des écritures doit appliquer une stratégie compatible avec leurs effets. Relances dans Symfony HttpClient.
Dans Symfony, nommez le service HTTP destiné à Salesforce et injectez-le dans l’adaptateur qui le consomme. Vérifiez son base_uri et sa configuration effective dans chaque environnement. En recette, contrôlez la méthode, l’URL produite et la désactivation des redirections avant de tester les droits. Un client réservé à Salesforce aide aussi à retrouver les paramètres d’une tentative quand plusieurs API transitent par le même worker.
Configurer OAuth et isoler les accès
Recensez les applications qui autorisent les workers Symfony. Depuis Spring ’26, la création de Connected Apps est restreinte. Salesforce recommande External Client Apps pour les nouvelles intégrations et les Connected Apps existantes peuvent continuer à fonctionner. Vérifiez le parcours OAuth, l’identité technique et les permissions sur les objets, champs et enregistrements. Applications Salesforce et OAuth 2.0.
Séparez les configurations de sandbox et de production. Stockez les secrets dans le coffre prévu et vérifiez l’URL d’instance avant d’y transmettre un jeton. Gardez les secrets et en-têtes d’authentification hors des traces. Après un refus d’authentification, le fournisseur de jetons peut renouveler une session valide selon son contrat. Un refus persistant passe en revue.
Rapprocher Lead, Account, Contact et Opportunity
Chaque objet a un cycle propre. Conservez l’identifiant du Lead, le compte retourné par la conversion et le contact associé. Un e-mail aide à retrouver un contact, tandis que la liaison ERP repose sur une référence qualifiée dans la bonne société. Si deux Leads rejoignent le même compte, alors comparez leurs liens avant de proposer une écriture. Le cas de deux Leads pour un client ERP détaille cette décision.
Sur un upsert REST par External ID, confirmez l’unicité du champ et le comportement de la version d’API utilisée. Pour la mise à jour, Salesforce documente HTTP 200 à partir de la version 46.0, avec un corps de réponse. Pour la création, il documente HTTP 201. Une mise à jour répétée peut déclencher des automatisations sur la même fiche. Réponses REST d’upsert par version.
Choisir entre REST et Bulk API 2.0
Utilisez REST lorsqu’une opération attend une réponse exploitable sur une fiche. Utilisez Bulk API 2.0 pour une charge asynchrone dont l’équipe sait rapprocher les résultats par ligne. Le point de bascule dépend de la latence utile, de la réserve d’appels et du coût de reprise. Mesurez ces trois éléments sur un volume représentatif.
Suivre chaque ligne après la fin du job
Associez les entrées à l’identifiant du job, à leur clé métier et à la version du mapping. Pour un lot fictif de 300 comptes, si 285 écritures sont confirmées et 15 sont rejetées pour validation, alors corrigez les 15 lignes concernées. Les résultats confirmés restent dans le journal. Vérifiez aussi les éventuelles lignes non traitées.
Le diagnostic Salesforce sous charge détaille les suites Bulk et la reprise Pub/Sub. Pour un export SOQL REST, vérifiez chaque continuation avant d’annoncer la fin, comme dans le cas du total annoncé avant la lecture des pages.
Traiter les changements et leurs rediffusions
Pour les changements Salesforce, identifiez le canal utilisé. Un consommateur Pub/Sub ouvre un flux et suit une position de reprise. Un webhook provenant d’un autre système a son propre contrat. Évitez de leur donner un type commun qui ferait perdre le sens du message et les règles d’ordre.
Pour CDC, traitez les champs selon le schéma et les indicateurs de modification ou de mise à null. Conservez le Replay ID après traitement ou prise en charge durable. La clé d’idempotence métier décrit l’effet attendu dans la cible. Lorsqu’un changement ancien arrive après une version récente, comparez les versions garanties ou relisez la source avant d’écrire. Décodage des changements CDC et rétention et reprise Pub/Sub.
Décider quoi faire selon la réponse Salesforce
L’exemple de lecture distingue le statut HTTP du code d’erreur Salesforce. Le code REQUEST_LIMIT_EXCEEDED peut accompagner un HTTP 403. Un autre 403 exige une revue des permissions ou du refus renvoyé. Surveillez la consommation de l’organisation et gardez une réserve pour les opérations prioritaires. Codes REST Salesforce et en-tête de suivi des limites.
| Réponse | Suite |
|---|---|
| 401 | Vérifier le jeton et le renouveler selon le contrat OAuth. |
| 403 avec code de quota | Temporiser les lectures et vérifier l’allocation touchée. |
| Autre 403 | Examiner le refus et les permissions du compte technique. |
| 404 | Vérifier le chemin, l’organisation et l’identifiant avant toute décision métier. |
| 429 ou 5xx | Examiner la cause et limiter les nouvelles tentatives sur les lectures. |
Les limites de temps de l’exemple bornent une tentative de lecture. Fixez séparément le nombre d’essais, le délai total et l’action de repli. Pour une écriture dont la réponse s’est perdue, le statut du transport ne suffit pas à prouver l’absence d’effet.
Compter les tentatives sur toute la chaîne
Supposons qu’un client HTTP tente une lecture jusqu’à trois fois, puis que la file fasse traiter le même message trois fois au total. Une seule lecture logique peut alors produire neuf appels. Pour assurer la traçabilité, gardez la même référence d’opération dans le journal et un identifiant distinct pour chaque tentative. Attribuez la responsabilité des relances à la couche qui connaît le délai métier et la capacité restante.
Pour une lecture, le worker peut espacer les tentatives et les arrêter lorsque son délai total est atteint. Si l’état est quota, alors mettez en attente le flux concerné et examinez l’allocation avant de le remettre en file. Si l’état est refused, demandez la vérification des droits ou de la règle qui a refusé l’appel.
Tester les réponses et les effets métier
Injectez MockHttpClient pour exercer les statuts, les réponses invalides et les erreurs de transport du client. Un 200 doit renvoyer une fiche identifiable. Un 403 de quota et un 403 de droits doivent produire deux décisions différentes. En sandbox, validez aussi les règles Salesforce et les effets en aval. Tests Symfony avec MockHttpClient.
La recette locale du code couvre 13 cas simulés. Un 403 contenant REQUEST_LIMIT_EXCEEDED doit donner l’état quota. Un refus sans ce code, y compris avec un corps HTML, doit donner refused. Un 200 sans identifiant déclenche une erreur. Chaque cas effectue une seule tentative via le client simulé, sans appel à Salesforce.
Relier les traces à l’opération métier
Pour chaque tentative, enregistrez l’organisation, la ressource, la référence de corrélation, la clé d’opération et le résultat. Le journal doit indiquer si la cible a répondu, ce qui a été confirmé et l’action attendue. Limitez les données personnelles et gardez les valeurs sensibles hors des logs.
Mesurez le délai des reprises et l’âge des écritures sans confirmation. Si un compte est lisible mais que la commande attend encore son numéro ERP, alors gardez les deux états visibles. Le support peut ainsi distinguer un accès Salesforce valide d’une étape métier encore bloquée.
Erreurs fréquentes dans un SDK Salesforce
Partager une stratégie de relance entre toutes les méthodes. Une lecture REST et une création de commande ont des conséquences différentes. Vérifiez les décorateurs HttpClient et les relances des workers sur chaque parcours.
Traiter un succès Composite comme une preuve unique. Examinez les résultats par sous-requête et les règles allOrNone. Le cas du compte annulé dans Salesforce Composite montre pourquoi un identifiant reçu peut rester inutilisable.
Laisser un import écraser un responsable commercial. Testez un import concurrent avec un Flow. Si la règle réserve OwnerId à Salesforce, alors le client doit écarter ce champ du mapping d’écriture externe et tracer le motif.
Plan d’action avant la mise en service
Décrire un flux et l’équipe qui l’exploitera
Choisissez une opération avec un début et une sortie vérifiables. Le contrat d’entrée précise l’organisation, l’objet, l’identité externe et la source autorisée. La sortie indique ce qui prouve le résultat, le statut renvoyé au métier et le service responsable des exceptions. Retenez aussi la configuration de version et de droits réellement testée.
Mesurez le délai entre la réception du dossier, l’écriture Salesforce et la preuve utile au consommateur. Fixez un seuil compatible avec le besoin commercial. Définissez la réserve de capacité pour les cas prioritaires et la procédure que le support utilisera si un import dépasse cette réserve.
Provoquer les incidents avant d’élargir le volume
Exercez un jeton expiré, un quota atteint et une règle de validation qui refuse un compte. Ajoutez un lot partiellement réussi, un événement rediffusé et une coupure après écriture. Comparez ce que le client a reçu avec les références réellement conservées dans Salesforce et dans l’ERP.
Avant l’ouverture, vérifiez que les écritures non confirmées restent identifiables et que les relances autorisées conservent une seule opération métier par clé. Si un scénario échoue, alors corrigez-le sur le périmètre pilote. Gardez les mêmes entrées et les décisions attendues pour la recette suivante.
- Documenter les accès, les champs autorisés et le client HTTP utilisé par chaque worker.
- Tester la perte d’une réponse, puis retrouver la preuve avant de relancer l’opération.
- Rapprocher les objets de recette et décider avec le métier quand élargir le flux.
Reprendre une écriture au résultat inconnu
En réalité, un appel expiré peut avoir déclenché une écriture et un Flow. Consignez la tentative et cherchez la preuve dans le système qui a autorité. Si une simple lecture reste incertaine, alors gardez le dossier en attente. Relancez avec la même référence lorsque la cible garantit la déduplication de cet effet ou lorsqu’une preuve confirme que la première tentative n’a eu aucun effet et ne peut plus aboutir. Conditions de relance dans la RFC 9110.
Par exemple, un compte retrouvé dans Salesforce ne prouve pas que l’ERP a reçu la commande. Rapprochez l’identifiant du compte et la référence de l’opération ERP séparément. Si la commande est confirmée, remontez sa référence au CRM. Si seule la fiche existe, vérifiez l’étape qui doit encore aboutir.
Isoler les organisations et les files de reprise
Retrouver la connexion du dossier à chaque tentative
Si un worker sert plusieurs organisations, transportez une référence interne d’organisation dans le message et résolvez-la dans la configuration de l’intégration. Conservez l’identifiant Salesforce de l’organisation, la version du mapping et la clé métier dans la trace de sortie. Le jeton et l’URL d’instance viennent de la connexion validée pour ce dossier.
Une demande préparée avant une migration peut rester dans la file. Si la configuration de reprise pointe vers une autre organisation ou un autre périmètre ERP, alors laissez la demande en attente. Le support compare les références et les droits avant de reprendre la transmission. Cette vérification protège aussi le rapprochement des dossiers dont le code client existe dans plusieurs sociétés.
Choisir quelle file peut repartir
Réservez la capacité de chaque organisation à ses opérations prioritaires. Dans un scénario fictif, l’export analytique et les lectures de comptes utilisent la même allocation. Lorsque la réserve prévue pour les commandes est atteinte, différez l’export et conservez sa position. Une autre organisation dont la capacité reste disponible peut continuer son traitement.
À la remise en service, reprenez les opérations selon leur décision enregistrée. Une lecture temporairement refusée, un champ rejeté et une écriture au résultat inconnu doivent rester reconnaissables. Le runbook précise quand ouvrir la file, quelles preuves relire et quel résultat confirme le rattrapage.
Approfondir les accès et les tests du client
Le socle des SDK CRM sous Symfony détaille les responsabilités qu’on peut partager entre plusieurs connecteurs. Pour isoler les accès par environnement, complétez-le avec les contrôles d’authentification et de sécurité API.
Pour transformer une réponse Salesforce ambiguë en cas reproductible, utilisez la méthode de test de contrat API. Conservez une réponse représentative, la décision attendue du client et l’état que le worker doit exposer après la reprise.
Conclusion — rendre chaque reprise vérifiable
Le client Symfony doit permettre de retrouver ce que Salesforce a renvoyé et la décision que le worker a prise. Le support peut alors distinguer une lecture refusée, un quota atteint et une écriture dont le résultat reste inconnu.
Commencez par un objet, une clé et un chemin de reprise. Vérifiez le comportement du client sur des réponses simulées, puis les règles Salesforce et les effets du flux en sandbox avant d’augmenter le volume.
Avec vos équipes métier et exploitation, Dawap peut cadrer le client Symfony et tester ses conditions de reprise dans votre intégration Salesforce–ERP.