Aller au contenu
Intégration API

SDK Close CRM sous Symfony : lire et vérifier une opportunité

Jérémy Chomel Dawap
  • Publié le : 15 novembre 2024
  • Mis à jour le : 12 novembre 2026
  • Temps de lecture : 10 minutes
Portrait de Jérémy Chomel

Un worker Symfony reçoit deux notifications pour la même affaire Close. La première déclenche une lecture qui attend le quota. La deuxième aboutit et publie l’étape gagnée. Quand le premier traitement reprend, le tableau commercial doit conserver l’état le plus récent.

Le client HTTP doit distinguer un délai imposé par Close, une opportunité introuvable et une réponse qui concerne le mauvais compte. Le worker prend ensuite la décision de reporter la lecture, de vérifier la correspondance ou de mettre à jour le tableau.

L’exemple lit une opportunité Close par son identifiant, vérifie son organisation et son lead, puis remet les données au traitement appelant. La recette part du dossier fictif SYM-204 et montre à quel endroit bloquer chaque anomalie.

Si plusieurs outils alimentent le même tableau commercial, notre offre d’intégration Close CRM couvre le connecteur et le rapprochement avec vos systèmes.

Partir de l’identifiant de l’affaire

SYM-204 est une affaire suivie dans deux outils. Le message reçu par le worker contient l’identifiant d’opportunité Close, l’organisation et le lead attendus. Le nom du compte sert à la lecture humaine. Une société peut porter deux opportunités actives, et le nom du lead peut changer entre la réception du webhook et le traitement.

L’API Close permet de lire une opportunité par GET /api/v1/opportunity/{id}/ et de sélectionner les champs avec _fields. Le client demande l’identifiant, l’organisation, le lead, le statut et la date de mise à jour. Ce minimum suffit pour vérifier le rattachement et alimenter la projection. Référence de la lecture d’une opportunité Close.

Choisir ce que le client HTTP prend en charge

Ce client convient à un service interne qui lit un compte Close avec une clé d’API. La clé est fournie par le gestionnaire de secrets de l’application. Close attend la clé comme identifiant HTTP Basic, avec un mot de passe vide. Un produit qui se connecte pour le compte de plusieurs utilisateurs doit traiter séparément l’autorisation OAuth et l’association entre identités et organisations. Modes d’authentification de l’API Close.

Le client reçoit un HttpClientInterface Symfony sans politique de relance automatique. Le gestionnaire de messages porte la limite de tentatives et l’heure du prochain essai. Cette répartition évite que Symfony HttpClient et le worker consomment chacun leur budget de reprise pour la même lecture. Configuration et gestion des réponses de Symfony HttpClient.

Écrire le client Symfony de lecture

Le client interroge uniquement l’hôte de Close et désactive le suivi des redirections. Il fixe un délai d’inactivité et une durée maximale de requête. Il lit le statut avant de décoder le corps, pour traiter une réponse 429 même quand son corps est vide.

<?php
declare(strict_types=1);

use Symfony\Contracts\HttpClient\HttpClientInterface;

final class CloseReadDeferred extends RuntimeException
{
    public function __construct(
        public readonly int $retryAfterSeconds,
    ) {
        parent::__construct('Quota de lecture Close.', 429);
    }
}

final class CloseOpportunityClient
{
    public function __construct(
        private readonly HttpClientInterface $http,
        private readonly string $apiKey,
        private readonly string $organizationId,
    ) {
    }

    public function find(
        string $opportunityId,
        string $leadId,
    ): ?array {
        if (preg_match('/^oppo_[A-Za-z0-9]+$/D', $opportunityId) !== 1) {
            throw new InvalidArgumentException('Identifiant Close invalide.');
        }

        $url = 'https://api.close.com/api/v1/opportunity/';
        $response = $this->http->request(
            'GET',
            $url . rawurlencode($opportunityId) . '/',
            [
                'auth_basic' => [$this->apiKey, ''],
                'headers' => ['Accept' => 'application/json'],
                'query' => [
                    '_fields' => 'id,organization_id,lead_id,status_id,date_updated',
                ],
                'timeout' => 4,
                'max_duration' => 8,
                'max_redirects' => 0,
            ],
        );
        $status = $response->getStatusCode();

        if ($status === 429) {
            $header = $response->getHeaders(false)['retry-after'][0] ?? '';
            $seconds = filter_var(
                $header,
                FILTER_VALIDATE_INT,
                ['options' => ['min_range' => 0]],
            );
            if ($seconds === false) {
                throw new UnexpectedValueException('Délai de quota Close illisible.');
            }
            throw new CloseReadDeferred($seconds);
        }

        if ($status === 404) {
            return null;
        }
        if ($status !== 200) {
            throw new RuntimeException('Échec de lecture Close.', $status);
        }

        $record = json_decode($response->getContent(false), true, 512, JSON_THROW_ON_ERROR);
        if (
            !is_array($record)
            || ($record['id'] ?? null) !== $opportunityId
            || ($record['organization_id'] ?? null) !== $this->organizationId
            || ($record['lead_id'] ?? null) !== $leadId
            || !is_string($record['status_id'] ?? null)
            || $record['status_id'] === ''
            || !is_string($record['date_updated'] ?? null)
            || $record['date_updated'] === ''
        ) {
            throw new UnexpectedValueException('Opportunité Close incohérente.');
        }

        return $record;
    }
}

Les délais de quatre et huit secondes sont des valeurs de recette. Ajustez-les au budget du worker et aux mesures de latence. Ce fragment cible des identifiants d’opportunité alphanumériques au format illustré par Close. Si votre intégration manipule d’autres objets, traitez leurs identifiants et leurs champs dans des méthodes dédiées.

Vérifier le lead et l’organisation

Une réponse 200 passe trois contrôles d’identité. L’identifiant de l’opportunité doit correspondre à la requête, l’organisation au compte configuré et le lead au rattachement attendu. Une divergence de lead peut suivre une correction réelle dans Close. Le worker signale la différence et garde la projection publiée jusqu’à validation de la nouvelle correspondance.

Validez ensuite la date et l’identifiant de statut dans le service qui tient le tableau. Celui-ci connaît les statuts configurés pour le compte. Après une migration, une étape peut garder son libellé tout en changeant d’identifiant. Faites valider la correspondance par les ventes avant d’accepter un nouveau statut dans les rapports.

Décider quoi faire de chaque réponse

  • 429. Le worker reporte la lecture au moins du délai renvoyé par Retry-After. Partagez cette limite entre les workers du même compte et du groupe d’endpoints concerné. Close expose également le temps de remise à zéro dans RateLimit. Limites de débit de Close.
  • 5xx ou transport interrompu. Le gestionnaire retente la lecture avec un délai croissant et un nombre d’essais borné. Les erreurs réseau peuvent apparaître à la lecture du statut ou du corps, car le client Symfony travaille de manière asynchrone.
  • 401 ou 403. Arrêtez les lectures concernées et vérifiez les identifiants et les droits. Consignez le compte et l’identifiant de corrélation sans recopier la clé ni les en-têtes d’authentification.
  • 404. Le client rend null. Le worker vérifie le rattachement et les événements récents avant de conclure à la suppression de l’affaire.
  • JSON invalide, incohérence d’identité ou réponse inattendue. Conservez le dernier état publié et ouvrez un diagnostic du contrat. Un délai de quota illisible doit aussi remonter au support.

Protéger les écritures à l’issue incertaine

Le client ci-dessus réalise des lectures. Pour ajouter une création, le gestionnaire d’écriture conserve une clé métier locale et distingue les opérations acceptées, refusées et indéterminées. Une réponse perdue après un POST peut correspondre à une création déjà appliquée.

Si l’identifiant d’activité est déjà connu, relisez cette activité. Si la cible est inconnue, recherchez une référence externe vérifiable et placez les cas ambigus en rapprochement. Une contrainte locale empêche deux workers de reprendre en parallèle la même intention. Le guide sur l’idempotence des écritures métier détaille les décisions à prendre quand la réponse manque.

Publier une projection sans retour arrière

Pour SYM-204, le worker B termine sa lecture avant le worker A et publie une version Close datée de 11 h 08. A reçoit ensuite une version datée de 11 h 07. La mise à jour locale vérifie et écrit la version dans une seule opération atomique pour cette opportunité. La projection reste à 11 h 08, même si deux workers comparent leurs résultats en même temps.

Convertissez les dates dans un format comparable qui conserve leur précision. Une version identique avec les mêmes champs peut être ignorée. Si deux lectures à date égale renvoient des états différents, conservez l’état publié et programmez une lecture de rapprochement. La résolution doit garder une trace de l’ambiguïté. Close précise que l’ordre de livraison des notifications peut varier. Règles de livraison des webhooks Close.

Distinguer un retard de lecture d’un mauvais rattachement

Suivez l’âge du plus ancien message en attente par organisation et le délai avant la prochaine lecture. Une série de 429 explique un retard de projection. Un 200 dont le lead diffère du rattachement attendu désigne un problème de correspondance que des tentatives supplémentaires risquent de répéter.

Sur le pilote, le support cherche SYM-204 et retrouve l’identifiant Close, la tentative, le statut HTTP, la version lue et la décision de publication. Si le volume de messages reportés augmente après la suspension d’un compte, isolez sa file pour que les autres organisations continuent à publier.

Tester les décisions avant le pilote

Contrôler le transport avec MockHttpClient

Dans le premier test, vérifiez la méthode GET, l’URL, la sélection _fields et l’authentification configurée avec une clé fictive. Faites varier le corps du 200, puis simulez un 404, un 429 avec sept secondes de délai, une panne de lecture du corps et une redirection. Un 200 d’une autre organisation doit être rejeté.

Le test du transport peut vérifier qu’un 429 est remis au worker avec son délai, sans seconde requête. Testez séparément le replanificateur avec une horloge contrôlée. La prochaine lecture de ce compte doit respecter les sept secondes et le budget de tentatives. Si ce budget est épuisé, le message reste visible pour le support.

Faire terminer les workers dans l’ordre inverse

Dans une recette avec la base de projection, préparez deux versions de SYM-204 et faites écrire la plus récente en premier. Vérifiez le résultat après la deuxième transaction. Rejouez ensuite exactement la même version et contrôlez que le tableau n’ajoute aucune ligne.

Ajoutez un cas où le statut n’existe pas dans la configuration du compte de test. L’opportunité doit rester visible avec le dernier état accepté et une décision explicite de rapprochement. L’ouverture à une deuxième organisation peut attendre que le support sache distinguer ces deux échecs.

Approfondir le contrat métier et le rapprochement

Le guide Close CRM sur la reprise du pipeline répartit les droits d’écriture entre les ventes, le marketing et la téléphonie. Il explique pourquoi une lecture fraîche du CRM doit préserver la décision prise sur l’affaire.

Le guide de rapprochement source et cible aide à examiner les divergences qui subsistent après une reprise. Pour définir des responsabilités communes à plusieurs CRM, partez du guide d’intégration CRM au SI.

Conclusion

Commencez par une lecture d’opportunité et une organisation de recette. Validez l’identité de l’objet avant de modifier le tableau commercial.

Faites décider au worker quand reprendre la lecture et quand isoler l’affaire. Un quota, un dossier introuvable et un rattachement incohérent demandent chacun une action identifiable.

Vérifiez ensuite que deux traitements concurrents laissent la version attendue dans le tableau. Le support doit retrouver l’origine d’un report ou d’un refus en partant du seul identifiant de l’affaire.

Notre équipe peut raccorder ces contrôles à vos files et à votre reporting dans le cadre d’une intégration Close CRM sous Symfony.

Portrait de Jérémy Chomel

Reliez le pipeline Close à votre application Symfony

Définissez les lectures nécessaires et le traitement des opportunités à rapprocher.

Articles recommandés

Guide Close CRM sur la reprise du pipeline commercial Intégration API Close CRM API : protéger le pipeline lors d’une reprise Lire l'article
  • 29 septembre 2024
  • Lecture ~9 min

Une affaire gagnée, un ancien score marketing et un appel dont la réponse se perd. Le dossier CL-318 montre comment retrouver l’activité dans Close et conserver la bonne étape du pipeline. Il donne aux ventes et au support une recette commune pour vérifier les droits d’écriture, les doublons et la reprise des webhooks.

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.

Testez les reprises sur vos opportunités Close

Contrôlez les quotas, les rattachements et la cohérence du tableau avant d’ouvrir le flux.