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