Intégration API

SDK CRM Freshsales sous Symfony : erreurs API, retries et suivi de run

Jérémy Chomel Dawap
  • Publié le : 29 janvier 2025
  • Mis à jour le : 12 novembre 2026
  • Temps de lecture : 11 minutes
  1. Pour qui isoler le client Freshsales
  2. Plan d’action pour un premier flux
  3. Préserver le budget de requêtes pour le diagnostic
  4. Erreurs fréquentes dans les appels Freshsales
  5. Donner un résultat exploitable au worker
  6. Choisir la durée de chaque requête
  7. Configurer le client HTTP Symfony
  8. Borner le mapping au contact rapproché
  9. Utiliser la clé de l’instance attendue
  10. Exemple PHP pour lire et modifier un contact
  11. Vérifier le résultat renvoyé par l’API
  12. Garder la même commande après redélivrance
  13. Traiter les quotas et les réponses perdues
  14. Tester avec MockHttpClient
  15. Tracer les reprises par compte Freshsales
  16. Rouvrir une file mise en pause
  17. Suivre la demande FS-2841 après un quota
  18. Matrice de décision pour les incidents
  19. Vérifier les conditions avant le passage en production
  20. Adapter le client aux autres flux CRM
  21. Guides complémentaires sur le mapping et les relances
  22. Conclusion. Relire avant de reprendre une écriture
Portrait de Jérémy Chomel

Un worker Symfony perd la réponse après avoir envoyé la mise à jour d’un contact Freshsales. Il tente de relire la fiche et reçoit un 429. La commande doit rester ouverte jusqu’au rapprochement. Le quota retarde la lecture dont le worker a besoin pour décider.

Le risque est de traiter ces deux issues comme une simple relance. Le client doit indiquer si la requête a reçu un refus, si la valeur a été confirmée ou si le résultat reste indéterminé. Le worker conserve l’intention d’écriture et choisit l’action suivante en fonction de cet état.

Le pilier Freshsales explique comment rapprocher un formulaire et son contact. Dans une intégration API Freshsales, le client Symfony reçoit ensuite un identifiant numérique confirmé et la liste des champs qu’il peut modifier.

Pour le contact fictif FS-2841, le formulaire apporte une fonction. La requête vise le contact 2841 et envoie seulement job_title. Le worker traite séparément l’opportunité D-731 et la relance qui dépend de son étape.

Pour qui isoler le client Freshsales

Une équipe qui reçoit des formulaires et des corrections d’ERP peut partager un client HTTP entre ses workers. Chaque flux garde ses autorisations de mapping. Le client applique les mêmes règles d’accès et de lecture du résultat, quelle que soit l’origine du message.

Plan d’action pour un premier flux

  1. Vérifiez d’abord l’URL de l’instance, la clé et l’accès en lecture sur un contact de recette.
  2. Autorisez ensuite la mise à jour de la fonction sur une fiche déjà rapprochée.
  3. Testez une réponse perdue, un quota et une réponse contenant un autre identifiant.
  4. Ouvrez la file quand le support sait distinguer ces trois issues et retrouver la demande d’origine.

Préserver le budget de requêtes pour le diagnostic

Quand un compte est limité, les lectures de rapprochement consomment aussi des requêtes. Réduire les nouveaux enrichissements laisse de la capacité à la vérification des commandes en attente. Si les deux files repartent ensemble, le diagnostic risque de rencontrer le quota avant même d’atteindre le premier contact incertain.

Erreurs fréquentes dans les appels Freshsales

Vérifiez le chemin complet du bundle et la méthode de mise à jour. Un mauvais préfixe peut donner un 404 avant que l’API n’examine l’identifiant. Un 401 doit orienter vers les réglages d’accès. Contrôlez les permissions si la clé permet de lire certaines fiches et reçoit un 403 sur l’écriture.

Donner un résultat exploitable au worker

Le client retourne un état et, si disponible, le statut HTTP. Il peut fournir l’identifiant et la fonction quand la réponse est exploitable. Le worker utilise ces éléments pour clôturer une commande, demander une correction ou prévoir une lecture. Les corps d’erreur bruts et les secrets restent hors du journal.

Choisir la durée de chaque requête

Le délai d’inactivité et la durée maximale ont des rôles différents. Ajustez-les aux temps de réponse observés et au budget du worker. Une durée trop courte multiplie les écritures à rapprocher. Si le délai est dépassé après l’envoi du PUT, le connecteur peut perdre la réponse alors que la requête a atteint Freshsales.

Configurer le client HTTP Symfony

Fixer l’origine dans la configuration

Injectez un client dédié dont la base_uri est l’URL HTTPS configurée pour le compte, avec son préfixe et sa barre finale. Pour le bundle d’exemple, elle se termine par /crm/sales/. La file transmet un identifiant numérique. L’URL et le secret viennent de la configuration. Désactivez le retry automatique sur le client d’écriture afin que Messenger garde la main sur la décision de reprise. Documentation Symfony HttpClient

Borner le mapping au contact rapproché

Le formulaire fournit une valeur de fonction, que le worker valide avant d’appeler le client. Un champ vide ne déclenche aucune écriture dans cet exemple. Pour gérer un effacement, donnez-lui sa propre règle métier et testez les valeurs vides et nulles acceptées sur l’instance.

Utiliser la clé de l’instance attendue

L’API Freshsales documente l’en-tête Authorization avec la forme Token token=<API_KEY>. Vérifiez l’URL du bundle et les droits de l’utilisateur associé à la clé. Gardez la valeur dans le stockage de secrets, séparée des données de la commande. L’option max_redirects est à zéro dans le client d’exemple. Authentification Freshsales

Exemple PHP pour lire et modifier un contact

Garder une méthode de lecture distincte

Le client ci-dessous utilise GET et PUT sur le contact identifié. L’écriture envoie uniquement le champ job_title dans l’objet contact. La lecture renvoie la valeur observée, y compris null lorsqu’elle est vide. Contrat de mise à jour Freshsales

<?php

use Symfony\Contracts\HttpClient\Exception\DecodingExceptionInterface;
use Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface;
use Symfony\Contracts\HttpClient\HttpClientInterface;

final class FreshsalesContactClient
{
    public function __construct(
        private readonly HttpClientInterface $client,
        private readonly string $apiKey,
    ) {
    }

    public function read(int $id): array
    {
        return $this->request($id);
    }

    public function updateJobTitle(int $id, string $jobTitle): array
    {
        $jobTitle = trim($jobTitle);
        if ($jobTitle === '') {
            return ['state' => 'demande_invalide'];
        }

        return $this->request($id, $jobTitle);
    }

    private function request(int $id, ?string $jobTitle = null): array
    {
        if ($id < 1) {
            return ['state' => 'demande_invalide'];
        }

        $options = [
            'headers' => [
                'Authorization' => 'Token token=' . $this->apiKey,
                'Accept' => 'application/json',
            ],
            'max_redirects' => 0,
            'timeout' => 4,
            'max_duration' => 12,
        ];
        $method = 'GET';
        if ($jobTitle !== null) {
            $method = 'PUT';
            $options['json'] = ['contact' => ['job_title' => $jobTitle]];
        }

        try {
            $response = $this->client->request($method, 'api/contacts/' . $id, $options);
            $status = $response->getStatusCode();

            if ($status === 429) {
                $retryAfter = $response->getHeaders(false)['retry-after'][0] ?? null;
                $response->cancel();

                return ['state' => 'quota', 'http' => $status, 'retryAfter' => $retryAfter];
            }

            if ($status !== 200) {
                $response->cancel();
                $state = $status === 408 || $status >= 500
                    ? 'resultat_indetermine'
                    : 'refus_http';

                return ['state' => $state, 'http' => $status];
            }

            $contact = $response->toArray(false)['contact'] ?? null;
        } catch (TransportExceptionInterface | DecodingExceptionInterface) {
            return ['state' => 'resultat_indetermine'];
        }

        if (!is_array($contact) || ($contact['id'] ?? null) !== $id
            || !array_key_exists('job_title', $contact)
            || ($contact['job_title'] !== null && !is_string($contact['job_title']))) {
            return ['state' => 'resultat_indetermine', 'http' => 200];
        }

        $observed = $contact['job_title'];
        $state = match (true) {
            $jobTitle === null => 'contact_lu',
            $jobTitle === $observed => 'valeur_confirmee',
            default => 'resultat_indetermine',
        };

        return ['state' => $state, 'http' => 200, 'id' => $id, 'jobTitle' => $observed];
    }
}

Vérifier le résultat renvoyé par l’API

Le code confirme le résultat du PUT uniquement si la réponse contient l’identifiant attendu et la fonction demandée. Une valeur différente appelle une lecture de rapprochement. Contrôlez dans l’instance les effets d’une automatisation sur les champs et les tâches, indépendamment de la valeur retournée.

Garder la même commande après redélivrance

Stockez une référence de commande stable et l’intention autorisée avant l’envoi. Si le worker s’arrête avant la confirmation, la redélivrance retrouve la commande à vérifier et appelle read(). Une réservation locale empêche deux workers d’émettre le même PUT simultanément. Les saisies dans Freshsales restent possibles pendant ce contrôle.

Traiter les quotas et les réponses perdues

Reporter la lecture au bon moment

Un 429 appelle une pause pour le compte concerné. Si la réponse fournit Retry-After, le worker interprète la date HTTP ou le nombre de secondes avant de programmer la prochaine tentative. En l’absence de valeur exploitable, appliquez la cadence de repli de votre file. Après une écriture incertaine, la prochaine opération reste une lecture. Erreurs de l’API Freshsales · Format de Retry-After

Tester avec MockHttpClient

Simulez le corps contact, une valeur vide, un identifiant inattendu, un refus et une coupure. Vérifiez le corps du PUT et le nombre d’appels. Rejouez ensuite le scénario dans le worker pour vérifier que la redélivrance d’une commande incertaine passe par read(). Le client et le routage de la file se testent séparément.

Tracer les reprises par compte Freshsales

Le journal conserve la référence de commande, le compte Freshsales ciblé, le type d’opération et son état. Mesurez l’âge des commandes à vérifier et le nombre de 429 par compte. Une file qui grossit après le retour des succès HTTP signale un rapprochement qui reste en retard.

Rouvrir une file mise en pause

Réservez d’abord un créneau aux lectures en attente. Comparez chaque fiche à l’intention enregistrée. Si le contact a changé depuis la demande, le référent CRM arbitre avant de rouvrir la commande. Les nouveaux enrichissements reprennent lorsque les décisions en attente sont retrouvables et que le budget de requêtes le permet.

Suivre la demande FS-2841 après un quota

Le PUT a été émis pour la fonction « Responsable logistique ». La réponse est perdue. La première lecture de rapprochement reçoit un 429 avec un délai de 45 secondes dans cet exemple fictif. Le worker conserve l’état indéterminé et programme un GET après le délai. Il clôture l’écart si la fonction est confirmée. Toute autre valeur exige une décision sur la demande initiale.

Matrice de décision pour les incidents

Reprise du contact Freshsales 2841
ObservationProchaine action
Le PUT confirme la fonction et l’identifiant.Clore l’écart de valeur. Contrôler les effets attendus séparément.
Le PUT reçoit 401 ou 403.Vérifier l’accès avant de réévaluer l’écriture.
Le PUT n’a plus de réponse.Conserver l’état indéterminé et programmer une lecture.
La lecture reçoit 429.Décaler la lecture en respectant le délai disponible.
La lecture retrouve une autre valeur.Comparer la demande et la fiche avant d’autoriser une nouvelle écriture.

Vérifier les conditions avant le passage en production

Rejouez les cas sur une instance de recette avec le bundle et les droits prévus. Vérifiez le format réellement renvoyé pour la fonction et les automatismes associés. Si une relecture incertaine provoque un deuxième PUT ou si un changement de fonction modifie le deal, suspendez l’ouverture du flux.

Adapter le client aux autres flux CRM

Pour ouvrir les comptes ou opportunités, créez un mapping et des tests propres à chaque ressource. La logique de quota et de journalisation peut être mutualisée. Une réponse valide pour un contact ne suffit pas à confirmer le rattachement ou l’étape d’un deal.

Guides complémentaires sur le mapping et les relances

Le guide API Freshsales aide à établir la correspondance et les autorisations avant l’écriture du client. Le guide des SDK CRM sous Symfony détaille ce qui peut être partagé entre éditeurs.

Pour décider d’un envoi après le changement d’une opportunité, le guide sur les relances Freshsales précise le contrôle d’éligibilité à effectuer au moment de l’envoi.

Conclusion. Relire avant de reprendre une écriture

Le SDK Freshsales prépare la requête avec un identifiant et un champ autorisé. Il restitue au worker la valeur observée ou une cause exploitable.

Une réponse perdue laisse la commande ouverte jusqu’au rapprochement. Un quota décale l’accès et conserve la décision déjà enregistrée.

Testez ensemble le code et la redélivrance du message avant d’élargir le flux. Le support doit pouvoir retrouver l’opération à vérifier et savoir à quel moment la relire.

Notre équipe d’intégration API Freshsales peut cadrer avec vos développeurs le client Symfony, la stratégie de quota et les essais de reprise.

Portrait de Jérémy Chomel

Cadrer votre client Symfony pour Freshsales

Vérifiez le bundle, les champs autorisés et les résultats que le worker doit conserver.

Articles recommandés

Freshsales API : cadrer les flux CRM sans dérive durable Intégration API Freshsales API : cadrer les flux CRM sans dérive durable Lire l'article
  • 8 septembre 2024
  • Lecture ~9 min

Un contact déjà suivi renvoie un formulaire après un salon. Sur le dossier fictif FS-2841, le connecteur doit reconnaître la soumission, mettre à jour la fonction sans réattribuer l’opportunité et réévaluer la relance si le deal a changé d’étape. Quatre cas de recette permettent de vérifier ces décisions dans Freshsales.

Freshsales : arrêter une relance devenue incompatible avec l’opportunité Intégration API Freshsales : arrêter une relance devenue incompatible avec l’opportunité Lire l'article
  • 21 avril 2026
  • Lecture ~3 min

L’opportunité D-731 est clôturée, puis un événement ancien la présente encore comme ouverte. Sur ce dossier fictif, trois décisions montrent quand appliquer la séquence, quand bloquer la relance et quand attendre une lecture de contrôle avant d’envoyer un message.

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é.

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.

Tester les reprises Freshsales

Reproduisez une réponse perdue et vérifiez le comportement du worker en cas de quota.