Intégration API

SDK Zoho CRM sous Symfony : upsert et reprise des leads

Jérémy Chomel Dawap
  • Publié le : 28 janvier 2025
  • Mis à jour le : 12 novembre 2026
  • Temps de lecture : 14 minutes
  1. Pour qui un client Zoho dédié est utile
  2. Plan d’action pour un premier flux de leads
  3. Distinguer la référence du lead et celle de l’événement
  4. Choisir les écritures que le connecteur peut déclencher
  5. Répartir les responsabilités dans Symfony
  6. Préparer la conversion du lead
  7. Renouveler l’accès OAuth dans le bon environnement
  8. Envoyer un lot et interpréter la réponse V8
  9. Reprendre une lecture paginée
  10. Configurer les champs et les automatisations
  11. Vérifier l’état après une réponse perdue
  12. Erreurs fréquentes et décisions de reprise
  13. Tester le connecteur avant la recette Zoho
  14. Donner au support une trace exploitable
  15. Suivre deux leads et une conversion en recette
  16. Vérifier les effets avant la bascule
  17. Approfondir l’architecture et les tests
  18. Conclusion — reprendre un lead sans doubler ses effets
Portrait de Jérémy Chomel

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

Décisions du worker par observation
ObservationDécisionContrôle
Rejet de champCorriger la ligne.Référence et code Zoho.
Accès refuséVérifier le jeton et les droits.Organisation et scopes.
Limitation 429Suspendre les nouveaux appels.Crédits et concurrence.
Réponse perdueRelire 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.

Portrait de Jérémy Chomel

Construire un connecteur Zoho CRM

Ciblez les modules, les droits OAuth et les cas de reprise du premier flux.

Articles recommandés

API Zoho CRM : sécuriser les écritures et la reprise Intégration API API Zoho CRM : sécuriser les écritures et la reprise Lire l'article
  • 6 septembre 2024
  • Lecture ~13 min

Un lot Zoho CRM accepte un contact et rejette le suivant. Retrouvez la fiche acceptée par sa clé source, reprenez uniquement la ligne corrigée et vérifiez si l’ERP a déjà reçu une demande. Le cas suit aussi la perte d’une réponse, le renouvellement des notifications et les décisions que le support doit pouvoir justifier.

Illustration du guide sur les adaptateurs CRM sous Symfony Intégration API SDK API CRM : unifier les connecteurs sous Symfony Lire l'article
  • 24 janvier 2025
  • Lecture ~17 min

Une opportunité gagnée part vers l’ERP et la réponse expire. Le socle Symfony doit retrouver la commande avant tout nouvel envoi, puis inscrire sa référence dans le CRM. Voyez quelles décisions partager, quels contrôles confier aux adaptateurs et comment tester la lecture d’un deal Pipedrive avec un client simulé.

Observabilité API et runbooks pour piloter le run en production Intégration API Observabilité API et runbooks : piloter le run en production Lire l'article
  • 24 mars 2025
  • Lecture ~28 min

L’observabilité API tient quand les SLO, les logs corrélés, les traces et les modes opératoires racontent la même histoire au support. Sans ce socle, les alertes arrivent trop tard, les incidents se répètent et le run devient une enquête artisanale au lieu de rester pilotable. Chaque alerte débouche ainsi sur un diagnostic, un seuil de gel et une preuve de clôture.

Testing API : fiabilisez vos intégrations – guide 2025 Intégration API Testing API : fiabilisez vos intégrations – guide 2025 Lire l'article
  • 15 août 2024
  • Lecture ~14 min

Tester une API utilement ne consiste pas à cocher un happy path. Le vrai enjeu est de savoir si la reprise, le rejet et le support restent lisibles quand un lot part en production. Reliez le sujet à notre offre d’intégration API pour réduire le coût complet d’un écart avant l’incident. Le support garde un cadre lisible.

Recetter vos écritures Zoho

Vérifiez les rejets, les réponses perdues et les effets des conversions avant la bascule.