Le worker Symfony envoie deux leads à Zoho CRM. Le premier est accepté, le second est rejeté parce qu’il lui manque un nom. Si le connecteur considère le lot comme réussi, le second lead disparaît de la file. S’il renvoie les deux fiches, un workflow peut repartir pour le lead déjà accepté.
Le risque vient d’une décision prise au niveau du lot alors que Zoho renvoie un résultat par fiche. Le client HTTP doit conserver l’ordre des entrées, leur associer les résultats et signaler les écritures dont l’issue reste incertaine. Le worker décide ensuite quoi reprendre.
Le scénario fictif suit WEB-104, issu d’un formulaire, et PARTNER-205, issu d’un import. Un exemple PHP lit le résultat d’upsert et distingue une réponse partielle, un accès à vérifier, une limitation et une réponse perdue.
Dans une intégration API Zoho CRM, cette séparation facilite la recette des automatisations. Le pilier Zoho CRM explique d’abord qui a le droit de modifier chaque champ. Ici, le code applique ces décisions à l’entrée des leads et à leur conversion.
Pour qui un client Zoho dédié est utile
Le découpage devient utile dès qu’un contrôleur web et un worker importent des leads par des chemins différents. Les deux producteurs peuvent partager la même validation, le même client Zoho et la même façon de lire les rejets. Ils gardent leur propre règle de prise en charge lorsqu’une fiche est incomplète.
Pour un flux unique, commencez avec un adaptateur et un journal par fiche. Introduisez une file distincte pour la conversion quand le délai de reprise ou les dépendances à Accounts et Contacts le justifient.
Plan d’action pour un premier flux de leads
Commencez par un producteur et un module. Le responsable Zoho vérifie le nom API du champ de rapprochement. Le développeur relève les champs envoyés et le support confirme qu’il peut retrouver une fiche à partir de la référence source.
- Attribuer une référence stable par lead et une identité distincte à chaque événement.
- Tester une réponse complète, un rejet isolé et une réponse perdue.
- Nommer le responsable qui peut relire le CRM et rouvrir la file de reprise.
Ouvrez ensuite la conversion sur les leads dont les correspondances sont connues. Différez les écritures de Deals tant que le support ne peut pas confirmer le contact, le compte et le résultat d’une conversion déjà envoyée.
Distinguer la référence du lead et celle de l’événement
WEB-104 désigne le lead du site. L’événement de version 7 désigne une mise à jour précise de ce lead. Conservez la clé du producteur avec la référence et sa version. Un nouvel événement peut viser la même fiche sans reprendre le même contenu.
Si un événement déjà confirmé revient avec la même version, alors le worker restitue la décision du journal. Si la version est identique et le contenu diffère, alors il bloque l’écriture pour arbitrage. Une date de réception ou un identifiant de corrélation d’un appel ne suffit pas à reconnaître l’événement métier.
Choisir les écritures que le connecteur peut déclencher
Le site renseigne les coordonnées de qualification de WEB-104. L’équipe commerciale décide de son responsable et de son stade dans Zoho. L’ERP fournit les données de facturation du compte une fois le rattachement validé.
Le mapping doit donc omettre les champs que le producteur n’a pas le droit d’écrire. Une correction de coordonnées ne doit pas transporter un propriétaire issu d’un ancien export. Vérifiez ce partage dans le contrat de synchronisation CRM, avant de l’encoder dans l’adaptateur.
Répartir les responsabilités dans Symfony
Le mapper transforme la commande métier en champs Zoho. Le client connaît la version d’API, le domaine, l’authentification et le format des réponses. Le worker décide si l’écriture est terminée, si une lecture de contrôle est nécessaire ou si le dossier doit être transmis au support.
Pour garantir la traçabilité, le worker enregistre la commande, la clé métier et la tentative avant l’appel. Après la réponse, il conserve la décision par ligne. Une file dédiée porte la réconciliation des résultats incertains. L’idempotence est vérifiée par le journal et par la relecture de la fiche ou de l’action aval.
Préparer la conversion du lead
La conversion Zoho peut rattacher un lead à un compte ou à un contact existant. Les options de conversion aident à repérer les correspondances. Faites valider le compte et le contact, puis transmettez les identifiants retenus quand ces fiches existent déjà. Enregistrez les identifiants renvoyés pour les objets effectivement produits. Conversion d’un lead dans Zoho CRM
Si Zoho retourne ID_ALREADY_CONVERTED, alors vérifiez le résultat de la conversion et la destination du deal avant de reprendre. Si le support retrouve le contact mais ne peut pas prouver quelle opportunité lui correspond, laissez le dossier à arbitrer. L’action commerciale n’est confirmée qu’une fois ses relations vérifiées.
Renouveler l’accès OAuth dans le bon environnement
Utilisez le domaine Zoho Accounts de l’autorisation pour appeler le renouvellement. Zoho renvoie notamment api_domain. Associez ce domaine au client, à l’organisation et à l’environnement attendus avant d’envoyer un jeton. L’exemple PHP utilise un domaine européen fixé pour le scénario. Renouvellement OAuth chez Zoho
Un renouvellement partagé entre les workers évite que tous renouvellent le même accès au même instant. Sur une erreur d’accès, vérifiez le code Zoho, la région et les scopes avant de décider. Une autorisation qui manque sur Leads exige une correction d’accès. Un renouvellement automatique ne lui donnera pas de droits supplémentaires.
Envoyer un lot et interpréter la réponse V8
Fixer la clé de recherche de doublons
Dans ce scénario, Lead_Ref est un champ personnalisé de Leads configuré comme unique. Le client le désigne dans duplicate_check_fields. Vérifiez les noms API et les champs obligatoires dans votre layout. Les valeurs de test WEB-104 et PARTNER-205 sont fictives. Contrat d’upsert V8 de Zoho CRM
En production, le mapper valide les champs avant l’envoi. En recette, on omet volontairement Last_Name sur PARTNER-205 pour observer le rejet lors d’une insertion. Zoho peut alors renvoyer un 207 avec une décision par entrée, dans l’ordre du lot.
Conserver le lien entre la requête et chaque résultat
Voici l’adaptateur d’un lot de leads. Il attend une liste ordonnée de lignes, avec des références normalisées par le mapper. Configurez une durée maximale sur le client Symfony injecté et laissez la décision de reprise au worker. L’adaptateur désactive les redirections. Client HTTP et exceptions Symfony
use Symfony\Contracts\HttpClient\Exception\DecodingExceptionInterface;
use Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface;
use Symfony\Contracts\HttpClient\HttpClientInterface;
function upsertZohoLeadBatch(HttpClientInterface $http, string $token, array $rows): array
{
if (!array_is_list($rows) || $rows === [] || count($rows) > 100) {
throw new InvalidArgumentException('Fournir une liste de 1 à 100 leads.');
}
$references = [];
foreach ($rows as $row) {
$reference = is_array($row) ? ($row['Lead_Ref'] ?? null) : null;
if (!is_string($reference) || trim($reference) === '' || isset($references[$reference])) {
throw new InvalidArgumentException('Chaque lead doit avoir une référence distincte.');
}
$references[$reference] = true;
}
try {
$response = $http->request('POST', 'https://www.zohoapis.eu/crm/v8/Leads/upsert', [
'headers' => ['Authorization' => 'Zoho-oauthtoken ' . $token],
'json' => ['data' => $rows, 'duplicate_check_fields' => ['Lead_Ref']],
'max_redirects' => 0,
]);
$status = $response->getStatusCode();
if (!in_array($status, [200, 201, 207], true)) {
$result = ['status' => match ($status) {
401, 403 => 'check_access',
429 => 'rate_limited',
default => 'observe',
}, 'http' => $status];
try {
$code = $response->toArray(false)['code'] ?? null;
if (is_string($code) && $code !== '') {
$result['code'] = $code;
}
} catch (DecodingExceptionInterface | TransportExceptionInterface) {
// Le statut HTTP reste disponible.
}
return $result;
}
$items = $response->toArray(false)['data'] ?? null;
} catch (TransportExceptionInterface | DecodingExceptionInterface) {
return ['status' => 'observe'];
}
if (!is_array($items) || !array_is_list($items) || count($items) !== count($rows)) {
return ['status' => 'observe'];
}
$results = [];
foreach ($items as $index => $item) {
$result = ['reference' => $rows[$index]['Lead_Ref'], 'status' => 'observe'];
if (is_array($item)) {
$code = $item['code'] ?? null;
$details = $item['details'] ?? null;
$id = is_array($details) ? ($details['id'] ?? null) : null;
if (($item['status'] ?? null) === 'success' && $code === 'SUCCESS'
&& is_string($id) && trim($id) !== '') {
$result = array_replace($result, ['status' => 'confirmed', 'id' => $id]);
} elseif (($item['status'] ?? null) === 'error' && is_string($code)
&& $code !== '' && $code !== 'SUCCESS') {
$result = array_replace($result, ['status' => 'rejected', 'code' => $code]);
}
}
$results[] = $result;
}
return ['status' => 'results', 'rows' => $results];
}
Le worker conserve la référence de la ligne avec l’identifiant Zoho renvoyé pour un succès. Un rejet de ligne garde son code. Un champ manquant appelle une correction et un code inconnu demande un diagnostic. Une réponse de succès illisible, un résultat sans identifiant ou un nombre de résultats incohérent déclenchent une vérification de l’état.
Reprendre une lecture paginée
Pour le rapprochement incrémental, Get Records accepte le filtre temporel If-Modified-Since. Demandez explicitement les champs nécessaires. Conservez la borne et le contexte de la lecture jusqu’à la validation de la dernière page. Les jetons de pagination dépendent de l’utilisateur et de la requête. Lecture et pagination de Zoho CRM
Si le jeton expire, relancez la fenêtre de rapprochement depuis le dernier point confirmé. Une fenêtre de recouvrement permet de revoir des fiches modifiées pendant la pagination. Dédupliquez sur les identifiants Zoho et la version observée. Lorsque le flux doit aussi suivre les suppressions, prévoyez une collecte adaptée.
Configurer les champs et les automatisations
Le nom Lead_Ref et les valeurs de test appartiennent au scénario. Avant de brancher votre organisation, vérifiez le nom API, l’unicité et les champs obligatoires. Consignez le mapping dans la configuration de l’environnement concerné.
L’upsert peut déclencher les automatisations associées lorsque trigger est omis. Vérifiez les workflows, les validations et les effets aval avec l’administrateur Zoho. En recette, isolez les notifications et les demandes envoyées à l’ERP avant d’injecter les cas d’échec.
Vérifier l’état après une réponse perdue
Le risque est de croire qu’un timeout prouve que le serveur a refusé le lot. La coupure peut survenir après l’écriture de WEB-104. Si la réponse manque, alors recherchez la fiche par la référence prévue et vérifiez l’égalité exacte de la clé dans le résultat. Contrôlez les champs réellement écrits et vérifiez aussi si le workflow a déjà notifié le commercial.
Deux workers ne doivent pas reprendre la même version au même moment. Réservez le traitement par clé d’événement dans un stockage durable. Si le worker tombe après l’envoi, sa reprise passe d’abord par la lecture Zoho et le journal des effets. Une contrainte d’unicité dans le journal prévient deux réservations locales, tandis que la relecture couvre la coupure entre l’appel distant et la confirmation locale.
Au redémarrage, traitez une réservation expirée comme une tentative à vérifier. Si l’ancien worker revient ensuite avec une réponse, rattachez-la à son identifiant de tentative. La mise à jour du journal doit vérifier que cette tentative est encore celle qui peut conclure le dossier. Cela évite qu’une réponse tardive efface une décision prise lors de la reprise.
Erreurs fréquentes et décisions de reprise
| Observation | Décision | Contrôle |
|---|---|---|
| Rejet de champ | Corriger la ligne. | Référence et code Zoho. |
| Accès refusé | Vérifier le jeton et les droits. | Organisation et scopes. |
| Limitation 429 | Suspendre les nouveaux appels. | Crédits et concurrence. |
| Réponse perdue | Relire avant le rejeu. | Fiche et effet aval. |
Le statut 429 appelle un diagnostic à partir du code Zoho et des mesures de la file. La concurrence et les crédits sont deux limites distinctes. Réduisez les appels simultanés en cas de saturation de concurrence et suivez la consommation si le budget de crédits est en cause. Limites de l’API Zoho
Tester le connecteur avant la recette Zoho
Avec MockHttpClient, vérifiez l’URL V8, l’ordre des références, le champ de rapprochement et le traitement de 207. Simulez un rejet, un nombre de résultats incohérent, une erreur réseau et un corps invalide. Un faux succès sans details.id doit rester à observer.
La recette dans une organisation Zoho dédiée confirme ensuite les droits OAuth, le layout et le comportement des workflows. Pour organiser les jeux de données et les preuves de validation, utilisez la méthode des tests d’intégration API.
Donner au support une trace exploitable
Le runbook doit relier le module, la référence source, l’identifiant Zoho, la corrélation et la décision de reprise. La journalisation masque les jetons et les coordonnées personnelles. Le support doit retrouver le rejet à corriger sans recevoir le contenu complet de la fiche.
Suivez le délai du plus ancien événement, le nombre de résultats incertains et les écritures qui attendent une correction. Une file qui grossit alors que les appels restent rapides peut signaler un conflit de mapping. Le parcours observabilité API et runbooks détaille les traces utiles au diagnostic.
Suivre deux leads et une conversion en recette
Envoyez WEB-104 avec son nom et PARTNER-205 sans nom depuis une file de recette. Le support doit retrouver l’identifiant Zoho de WEB-104, corriger PARTNER-205 à la source et réémettre uniquement cette ligne. Faites ensuite perdre une réponse pour vérifier que le worker attend le résultat de la relecture avant de repartir.
Après qualification, convertissez WEB-104 avec le compte et le contact validés. Comparez les identifiants de la réponse aux fiches relues. Simulez le retour d’une commande de conversion déjà traitée. Le dossier est clos quand le support peut retrouver les mêmes relations et confirmer que le processus commercial n’a été lancé qu’une fois.
Vérifier les effets avant la bascule
Le support doit pouvoir suspendre la file d’écriture tout en conservant les événements reçus. Dans le plan de repli, prévoyez la réconciliation des commandes encore en attente et attribuez la responsabilité de la remise en service. Toute correction aval garde la référence de l’action d’origine.
Avant d’élargir le pilote, relisez les traces du lot, du rejeu et de la conversion avec l’administrateur Zoho. Vérifiez ce que chaque workflow a fait dans cette organisation. Les seuils d’alerte se fixent avec les personnes qui reprennent la file, en fonction des délais attendus par le commerce.
Approfondir l’architecture et les tests
Si plusieurs CRM partagent le même runtime Symfony, la conception des adaptateurs CRM aide à partager le transport et les traces tout en gardant une lecture des réponses propre à chaque API.
Pour trancher l’autorité d’un champ, le rôle de Flow ou l’effet attendu dans l’ERP, revenez au cadrage des écritures et de la reprise dans Zoho CRM.
Conclusion — reprendre un lead sans doubler ses effets
Enregistrez une décision par référence et par version, avec l’identifiant Zoho lorsque l’écriture est confirmée. Après un rejet, corrigez la ligne et relancez cette seule entrée.
Si une réponse manque, relisez la fiche et les effets en aval avant d’autoriser une nouvelle écriture. Pour la conversion, exigez aussi la correspondance du compte et du contact.
Le test de bascule consiste à confier au support les dossiers WEB-104 et PARTNER-205 avec le journal, puis à vérifier qu’il retrouve la bonne fiche et la décision attendue pour chacun.
Pour mettre ce parcours en place dans votre intégration API Zoho CRM, Dawap vous accompagne sur le client Symfony, les règles du worker et la recette des écritures déjà engagées.