Aller au contenu
Intégration API

SDK HubSpot sous Symfony : client PHP et contrats testés

Jérémy Chomel Dawap
  • Publié le : 25 janvier 2025
  • Mis à jour le : 11 novembre 2026
  • Temps de lecture : 16 minutes
Portrait de Jérémy Chomel

Un worker Symfony crée une opportunité HubSpot. La réponse se perd et le worker renvoie le même POST. Le risque apparaît quand la reprise répète l’écriture avant que le support ait vérifié son résultat. Gardez une clé par demande et vérifiez les requêtes construites par le SDK avant d’ouvrir le flux.

Le laboratoire installe hubspot/api-client 15.1.0 et compile la configuration de services Symfony. Il vérifie deux pages de contacts, un PATCH limité, une création avec associations et les erreurs 429 et 404. Les routes observées dans ces tests sont en v3. Les réponses sont simulées.

Pour cadrer une intégration HubSpot, ERP et logiciels métier, choisissez les propriétés à écrire, la clé de demande et les étapes que le support pourra reprendre. Faites valider ces décisions avec les responsables des flux CRM.

Pour qui utiliser le SDK HubSpot sous Symfony

Ces exemples s’adressent à une équipe qui maintient déjà une application PHP et doit synchroniser des contacts ou créer des transactions dans un portail identifié. Pour chaque opération, définissez l’entrée acceptée, la sortie que le service doit conserver et la décision à prendre si HubSpot renvoie une erreur. Ce contrat permet de faire évoluer le transport sans changer les décisions de l’ERP.

Le paquet officiel hubspot-api-php maintenu par HubSpot fournit une arborescence de découverte et des clients générés. Votre service métier doit conserver un vocabulaire interne stable, puis traduire sa décision vers ces modèles à la frontière du connecteur.

Gardez les règles de facturation et de qualification dans votre application. L’adaptateur construit un SimplePublicObjectInput à partir des propriétés autorisées après rapprochement avec l’ERP. Les exemples de connecteurs CRM sous Symfony montrent ce découpage avec plusieurs fournisseurs.

Si une route datée n’est pas exposée par le SDK retenu, alors utilisez un client HTTP pour cette opération et testez le contrat REST correspondant. Comparez le chemin, le payload et les erreurs. Pour une migration, comparez aussi le contenu de la réponse et vérifiez quelles propriétés restent disponibles.

Installer une version précise et conserver les dépendances

composer require hubspot/api-client:15.1.0
composer show hubspot/api-client
php sdk_lab.php

Cette version demande PHP 8.1 ou supérieur et les extensions curl, json et mbstring. Dans notre installation isolée, Composer a résolu Guzzle 8.3.1 et PSR-7 3.2.0. Ce résultat décrit le laboratoire ; votre application doit conserver son propre fichier de verrouillage et vérifier ses contraintes avant une mise à jour.

L’archive reproductible HubSpot contient sdk_lab.php, services.yaml et check_container.php, avec les programmes métier Python. Si votre autoload Composer se trouve ailleurs, renseignez DAWAP_COMPOSER_AUTOLOAD avec son chemin.

Exécutez ces commandes dans le dossier extrait de l’archive. Pour un projet d’intégration, installez le paquet dans l’application qui exécute les échanges et versionnez composer.lock. En CI, utilisez composer install pour rejouer les mêmes versions avec les tests.

Injecter le client et garder les secrets côté serveur

services:
    dawap.hubspot.http:
        class: GuzzleHttp\Client
        arguments:
            - { timeout: 15, connect_timeout: 5, allow_redirects: false }
    HubSpot\Discovery\Discovery:
        factory: ['HubSpot\Factory', 'createWithAccessToken']
        arguments: ['%env(HUBSPOT_ACCESS_TOKEN)%', '@dawap.hubspot.http']
        public: true

Le service est public uniquement pour permettre au petit programme de vérification de le récupérer. Dans une application, privilégiez un service privé injecté dans l’adaptateur. Les délais illustrent une politique locale à dimensionner selon le parcours ; ils ne constituent pas une recommandation HubSpot universelle.

La configuration charge le token depuis l’environnement du serveur. Pour un nouvel accès mono-compte, qualifiez une Service Key ; pour plusieurs comptes, implémentez le cycle OAuth et la rotation des jetons. Les Service Keys officielles ne dispensent pas de vérifier les scopes et les fonctionnalités nécessaires.

Le programme check_container.php charge ce YAML et compile un ContainerBuilder Symfony. Exécutez-le avec les composants DependencyInjection, Config et Yaml installés, ou indiquez un autoload Symfony existant via DAWAP_SYMFONY_AUTOLOAD. Il instancie la découverte des contacts avec un token fictif. Vérifiez l’injection réelle du secret lors de la recette du worker.

Parcourir les pages de contacts avec le curseur retourné

$hubspot = \HubSpot\Factory::createWithAccessToken($token, $http);
$api = $hubspot->crm()->contacts()->basicApi();
$after = null;
do {
    $page = $api->getPage(
        limit: 100,
        after: $after,
        properties: ['email', 'firstname']
    );
    foreach ($page->getResults() as $contact) {
        // Transmettre la lecture à votre stockage avant de confirmer le lot.
        $ids[] = $contact->getId();
    }
    $after = $page->getPaging()?->getNext()?->getAfter();
} while ($after !== null);

La vérification de pagination inspecte l’historique HTTP de Guzzle. Elle vérifie deux contacts sur deux pages, le header Bearer, la limite et le curseur transmis au deuxième appel. L’endpoint construit est /crm/v3/objects/contacts, sans token dans l’URL.

En production, consignez le portail, les filtres et le curseur avec chaque lot. Si l’API répète un curseur, alors arrêtez la collecte et gardez la dernière position validée. Une position doit correspondre à des données déjà enregistrées. Les objets et associations de l’API HubSpot déterminent les identifiants à conserver pendant cette collecte.

Par exemple, après deux pages reçues, une panne de stockage sur la deuxième doit laisser le curseur de cette page disponible pour la reprise. Enregistrez les contacts et la nouvelle position ensemble, ou rejouez l’écriture locale sur la clé portail et ID HubSpot. Fixez un plafond de pages par exécution pour qu’un import puisse rendre la main à la file.

Construire un PATCH qui préserve les autres propriétés

use HubSpot\Client\Crm\Contacts\Model\SimplePublicObjectInput;

$updated = $api->update('101', new SimplePublicObjectInput([
    'properties' => ['phone' => '+33102030405'],
]));

L’identifiant 101 appartient au jeu fictif. Le test vérifie la méthode PATCH, le chemin de cette fiche et le corps exact contenant uniquement phone. Aucun changement d’email, de responsable ou de cycle de vie ne se glisse dans la requête.

Une application réelle résout d’abord l’identifiant canonique et vérifie si la tâche est encore autorisée. Le programme métier patch_contact ajoute cette barrière, une liste de propriétés admises et une réservation durable de l’effet. Le cas de correction d’un contact depuis l’ERP traite aussi les effacements explicites et le 404 sans création de secours.

Après un timeout, l’absence de reçu ne signifie pas que le PATCH a échoué. Une correction commerciale peut être intervenue depuis. Relisez les champs et leur contexte avant de prendre une décision de rapprochement ; rejouer l’ancien corps peut écraser une valeur désormais légitime.

Créer une transaction avec les modèles d’association

Le laboratoire construit un SimplePublicObjectInputForCreate du namespace Deals. Chaque lien est un PublicAssociationsForObject qui contient un PublicObjectId et une liste d’AssociationSpec. Les noms de propriétés PHP de ces modèles et les noms du JSON émis ne se confondent pas.

use HubSpot\Client\Crm\Deals\Model\AssociationSpec;
use HubSpot\Client\Crm\Deals\Model\PublicAssociationsForObject;
use HubSpot\Client\Crm\Deals\Model\PublicObjectId;

$contactLink = new PublicAssociationsForObject([
    'to' => new PublicObjectId(['id' => '101']),
    'types' => [new AssociationSpec([
        'association_category' => 'HUBSPOT_DEFINED',
        'association_type_id' => 3,
    ])],
]);

Dans le laboratoire, le type HubSpot 3 relie le deal à un contact et le type 5 désigne la société principale du deal. Le type 341 crée une association simple du deal vers une société. Le type 1 désigne la société principale du contact, dans le sens contact vers société. Vérifiez le sens et le rôle métier dans les types d’association documentés.

Le test prépare le deal, ses deux liens et des identifiants de pipeline et d’étape fictifs. Ces identifiants doivent être remplacés par des valeurs internes validées dans votre portail. Le SDK 15.1.0 construit ici POST /crm/v3/objects/0-3 et désérialise la réponse de création 201.

Le scénario demande B2B qualifiée et transaction HubSpot décide quand cette création est utile. Le sélecteur de société primaire vérifie le rattachement avant d’utiliser une correspondance ERP.

Traiter les erreurs fréquentes et les réponses perdues

Le test appelle getById avec deux réponses simulées. L’ApiException du client Contacts conserve le 429 et son Retry-After de dix secondes, puis le 404 du second appel. L’historique Guzzle montre les deux lectures et permet de vérifier l’absence de requête supplémentaire. Les décisions du worker restent à définir dans votre application.

SignalDécision de reprise
401 ou 403Suspendre le flux concerné et vérifier la connexion, ses droits et le portail.
429Reporter le travail selon les indications reçues et réduire la concurrence sur le compte.
404 sur une fiche connueVérifier l’identifiant, l’archivage et les fusions avant de décider d’une correction.
Erreur de validationCorriger les propriétés refusées avant d’autoriser une nouvelle tentative.
Résultat d’écriture inconnuGarder la réservation en attente et retrouver l’effet dans HubSpot.

Par exemple, avec le délai simulé de dix secondes, reprogrammez la lecture dans la file après ce délai et gardez le curseur associé au portail concerné. Les autres portails peuvent poursuivre leur collecte. Pour une écriture dont la réponse s’est perdue, la sortie attendue du rapprochement est l’identifiant confirmé ou un dossier à examiner par le support.

Le test vérifie aussi le nombre total d’appels. Dans le worker, réservez la clé de demande et l’empreinte du corps avant une création. Si un timeout survient après le départ du POST, alors laissez cette réservation en attente et recherchez le deal par une référence de demande qualifiée. Le support consigne l’ID retrouvé avant de reprendre les étapes suivantes.

Une hausse des 429 sans hausse des entrées suggère des recherches ou reprises trop fréquentes. Des contacts corrigés plusieurs fois sur la même journée peuvent révéler un conflit de sources. Mesurez ces écarts avec leur motif ; un taux global de réponses 200 ne permet pas de les diagnostiquer.

Exécuter les tests et lire leur portée exacte

Le fichier sdk_lab.php effectue vingt-quatre assertions sur six échanges Guzzle simulés. Il vérifie la construction et la désérialisation des appels retenus, sans joindre HubSpot. Le contrôle du conteneur démontre séparément que la factory et les arguments YAML peuvent être instanciés sous Symfony.

Les cinquante-huit tests Python prolongent les règles métier. Ils couvrent des réponses fabriquées et trois échanges HTTP sur localhost, dont un redirect refusé et un 429 sans retry automatique. La démonstration obtient un seul POST après deux présentations de la même demande, conserve une chaîne de fusion et bloque un ancien opt-in.

Avant d’ouvrir les flux, testez les droits, les propriétés et les suppressions dans un compte autorisé. Inventoriez les chemins émis. Les routes v3 du SDK testé entrent dans l’échéance de support des API v1 à v3 en septembre 2027. Les routes v4 suivent un calendrier distinct. Pour votre migration, vérifiez les contrats des endpoints datés dans votre version du client.

Plan d’action pour mettre le worker en service

Transporter une référence de décision plutôt qu’une fiche complète

Dans une application Symfony, le message de travail peut conserver le portail, l’identifiant source, la révision de la demande et le contrat à appliquer. Le worker retrouve ensuite les correspondances et les propriétés autorisées. Un payload intégral conservé pendant plusieurs jours risque de réintroduire une ancienne adresse, un responsable remplacé ou une préférence retirée.

Le laboratoire représente cette admission avec une génération de tâche. Avant un PATCH ou une création, il vérifie que la tâche est active et que son identité n’a pas été remplacée par un alias. Après fusion ou archivage, le worker doit reconstruire une décision actuelle. Une file technique qui sait répéter un message ne sait pas, à elle seule, si le métier l’autorise encore.

Le contrat de production doit maîtriser la course entre contrôle et départ de l’appel. Selon l’architecture, une réservation transactionnelle, un verrou par identité ou un mécanisme de génération contrôlée peut participer à cette protection. Le programme SQLite demeure séquentiel ; il sert de témoin pour la règle, sans fournir cette coordination distribuée.

Observer l’effet sans multiplier les données personnelles

Une trace utile contient l’opération et son état : réservée, confirmée ou à rapprocher. Elle relie la demande interne au portail et à l’objet obtenu. L’empreinte du corps permet de détecter une clé réutilisée avec un contenu différent ; elle ne remplace pas le contrôle d’accès à la donnée source et ne rend pas un stockage automatiquement anonyme.

Le coût caché apparaît lorsque chaque échec exige de chercher dans HubSpot, la file et un export ERP. Préparez une vue de diagnostic qui rapproche ces références avec le motif de retenue et la prochaine action. Elle doit permettre d’arrêter une seule identité en conflit sans suspendre toutes les lectures ni exposer des secrets aux opérateurs.

La démonstration confirme le deal 600 pour request-1. La répétition retrouve le même ID et le nombre de POST reste à un. Paradoxalement, un timeout peut survenir après une création réussie. Dans ce test, la réservation reste pending après réouverture de SQLite. Prévoyez dans le support un écran qui garde la demande en attente jusqu’au rapprochement.

Recevoir une version de paquet avant de l’ouvrir aux écritures

Lors d’une mise à jour du SDK, comparez les chemins et les corps HTTP des opérations utilisées, leurs modèles de réponse et leurs exceptions. Les assertions du laboratoire détectent par exemple un changement de chemin pour le deal ou un modèle d’association qui n’émettrait plus associationTypeId. Une compilation réussie ne vérifie pas ces contrats.

Exécutez d’abord les tests de construction, puis un parcours natif autorisé sur des objets de recette. Vérifiez les propriétés, les associations, les droits insuffisants et le comportement des automatismes existants. Une correction de téléphone peut déclencher un workflow dans le compte ; une réponse simulée n’observe pas cet effet secondaire.

  • Ouvrir le flux : les champs, les identifiants et les cas de reprise sont reçus, avec une surveillance accessible au support.
  • Différer la mise à jour : le nouveau paquet change un contrat encore utilisé sans adaptateur ni preuve de migration.
  • Refuser le rejeu : la réponse initiale reste inconnue, la tâche est suspendue ou l’identité n’est plus canonique.

Enfin, prévoyez le repli avant la diffusion : arrêt des nouvelles écritures, conservation des reçus et identification des dossiers produits avec la nouvelle version. Le retour au code précédent ne retire pas un deal déjà créé. Les règles de correction de ces objets doivent être qualifiées avec le responsable commercial, sans transformer un rollback logiciel en annulation métier implicite.

Relier les preuves techniques au dossier client

Conserver l’identité malgré les changements du CRM

Une fusion conserve des références historiques et peut révéler deux comptes ERP incompatibles. Le traitement fusion de contacts et identifiants ERP montre les alias persistés et la mise en attente. Le cas contact archivé et reprise invalide les tâches anciennes par génération.

Dans la démonstration, l’ancien identifiant 101 se résout en 301 après fusion. Sur un compte connecté, conservez l’alias avec le portail et bloquez l’écriture si plusieurs dossiers ERP revendiquent le même survivant. La file peut reprendre lorsque le support a validé la nouvelle correspondance et que le message reflète cette révision.

Séparer relation commerciale et autorisation de contact

Le parcours des préférences et retraits protège le canal et la finalité, sans déduire un opt-in de l’existence d’un contact. Le pilier CRM–ERP conserve de son côté les critères d’acceptation des documents de gestion.

Si une demande d’opt-in attend dans la file et qu’un retrait plus récent est enregistré, relisez la préférence avant l’appel. Gardez le résultat du contrôle avec sa révision dans la trace du worker. Cette décision laisse l’équipe traiter un devis ouvert tout en appliquant le retrait sur le canal concerné.

Conclusion : un client testé, puis un contrat métier vérifiable

Le SDK devient utile lorsque sa version, ses modèles et ses requêtes sont observables. La pagination, les associations typées et les erreurs doivent pouvoir être reproduites sans dépendre d’une démonstration manuelle sur des données clients.

Le journal métier prend ensuite le relais : il conserve les effets confirmés, bloque les résultats inconnus et invalide les tâches qui n’ont plus d’autorisation. Une mise à jour du paquet ne remplace aucune de ces décisions.

Pour cadrer votre intégration HubSpot sous Symfony, Dawap peut vous aider à vérifier les routes, les propriétés et les liens attendus, puis à tester le premier flux et sa reprise avec le support.

Portrait de Jérémy Chomel

Vérifiez les contrats du connecteur HubSpot

Ciblez les routes, les propriétés et les associations à valider avant d’ouvrir les écritures.

Articles recommandés

HubSpot API : contacts, associations et webhooks vérifiés Intégration API HubSpot API : contacts, associations et webhooks vérifiés Lire l'article
  • 4 septembre 2024
  • Lecture ~16 min

Un contact HubSpot peut avoir plusieurs sociétés associées. Comment retrouver le bon compte ERP et reprendre une écriture interrompue ? Vérifiez les accès, les associations et les signatures de webhooks. L’archive permet de reproduire ces contrôles en Python et de vérifier les requêtes du SDK PHP sur des données fictives.

HubSpot API : consentements et vérité CRM Intégration API HubSpot API : consentements et vérité CRM Lire l'article
  • 13 février 2024
  • Lecture ~20 min

Une personne se désinscrit à 10 h. Un fichier préparé la veille l’indique encore abonnée. Suivez le retrait depuis le formulaire jusqu’à l’outil d’envoi et vérifiez séparément le statut de la newsletter, la marque et le désabonnement global. L’exemple local reproduit le conflit et montre comment bloquer la reprise de l’ancien accord.

Fusion HubSpot : garder l’identité ERP Intégration API Fusion HubSpot : garder l’identité ERP Lire l'article
  • 25 octobre 2026
  • Lecture ~18 min

Une ancienne notification HubSpot vise le contact 101 après deux fusions. Retrouvez la fiche 301, conservez le compte E42 et vérifiez les tâches avant de les reprendre. Les exercices locaux montrent comment retrouver ces références après redémarrage et suspendre le dossier lorsque deux comptes ERP restent candidats.

HubSpot : un contact archivé revient Intégration API HubSpot : un contact archivé revient Lire l'article
  • 23 août 2025
  • Lecture ~16 min

Un import ERP peut recréer un contact HubSpot retiré si une recherche vide autorise la création. Vérifiez l’archive par le Record ID et retrouvez les tâches déjà en file. Deux exercices locaux montrent comment bloquer ces demandes, approuver une nouvelle reprise et maintenir un blocage de confidentialité lors d’une reprise ordinaire.

Testez la reprise avec votre équipe support

Dawap vous aide à vérifier les erreurs d’accès, les réponses perdues et les rapprochements avant la mise en service.